Custom component library

1. Initialize the project

In the directory where you want to create the project, run:

mccl init

The scaffolding prompts you for the following information:

1. Component library name: Enter the component library name.

   • Example: my-custom-components

   • Description: The name of the component library. This name is used as the category for your components in the materials panel by default.

2. Component library description: Enter the component library description.

   • Example: This is a custom component library based on antd

   • Description: Describe the purpose of your component library.

3. Component library global variable name: Enter the global variable name for the component library.

   • Example: MyCustomComponents

   • Description: Use PascalCase. The first letter must be uppercase, and subsequent characters can be uppercase letters, lowercase letters, or numbers. This name serves as a unique identifier. Do not modify it after it is set.

After initialization, a new project directory is created. The directory name matches the global variable name you entered.

Generated project structure:

YourGlobalName/
├── mobi.config.js          # Configuration file
├── package.json            # Project dependency configuration
├── tsconfig.json           # TypeScript configuration
├── tsconfig.node.json      # TypeScript configuration file for the Node.js environment
├── .gitignore              # Git ignore file
├── .nvmrc                  # Node.js version specification
├── README.md               # Project documentation
└── src/                    # Component source directory
    └── HelloMobi/          # Sample component
        ├── index.tsx       # Component implementation
        └── config.ts       # Component configuration

Note:

• Do not modify the global variable name after it is set, because it is the unique identifier for the component.

• Initialization creates a new folder in the current directory and does not overwrite existing files.

2. Enter the project directory and install dependencies

cd YourGlobalName  # Replace with your global variable name
npm install # or pnpm install

3. Start the debug mode

mccl dev
# or
npm run dev

Scenarios:

• Preview changes in real time during component development.

• Debug component configurations.

• Perform integration testing with the Mobi platform.

Stop the service:

Press Ctrl+C to exit debug mode.

• Note:

  • Debug mode must be used with the Mobi platform. For more information, see the following sections.

4. Build the production version

mccl build
# or
npm run build

Build artifacts:

After the build completes, a dist.zip file is generated in the project's root directory. Upload this build artifact to the Mobi console to use it. For more information, see the following sections.

1. mccl -v / --version - View the version

Function: View the current version of the scaffolding.

Usage:

mccl -v
# or
mccl --version

2. mccl -h / --help - View help

Function: View the help documentation for the scaffolding.

Usage:

mccl -h
# or
mccl --help

mobi.config.js - Core configuration file

mobi.config.js is the core configuration file for the scaffolding and is located in the project root directory. It defines the basic information of the component library, component scanning rules, and build configurations.

// Mobi custom component library configuration file
export default {
  // === Basic library information ===
  library: {
    name: "QiDian Components",
    description: "This is a custom component library",
  },

  // === Component configuration ===
  components: {
    // Component directory
    dir: "src",
    // Specifies whether to automatically scan the component directory
    autoScan: true,
    // Manually specify components (used when autoScan is false)
    include the following: [],
    // Excluded components
    exclude: [],
  },

  // === Build configuration ===
  build: {
    // UMD global variable name (PascalCase)
    globalName: "MyCompoLib",
    // Output directory
    outDir: "dist",
    // External dependencies (not bundled)
    external: ["react", "react-dom", "antd", "dayjs", "@ant-design/icons"],
    // Global variable mapping
    globals: {
      react: "React",
      "react-dom": "ReactDOM",
      antd: "antd",
      dayjs: "dayjs",
      "@ant-design/icons": "AntdIcons",
    },
  },
};

library - Basic library information

Function: Defines the basic metadata for the component library.

Parameters:

components - Component scanning configuration

Function: Configures component scanning rules to tell the scaffolding how to find and identify components.

Parameters:

components: {
  dir: 'src',
  autoScan: true,
  exclude: ['_internal', 'utils', 'types'],
}

src/
├── Button/          ✅ Recognized as the Button component
├── Input/           ✅ Recognized as the Input component
├── Card/            ✅ Recognized as the Card component
└── utils/           ❌ Excluded (in the exclude list)

components: {
  dir: 'src',
  autoScan: false,
  include the following: ['Button', 'Input', 'Card'],
}

build - Build configuration

Function: Configures build-related parameters, including the output directory, external dependencies, and global variable mapping.

Parameters:

outDir: 'dist'  // Build artifacts are output to the dist.zip directory.

external: [
  'react',        // React library
  'react-dom',    // ReactDOM library
  'antd',         // Ant Design component library
  'dayjs',        // Date handling library
  '@ant-design/icons',       // Ant Design icon library
]

globals: {
  'react': 'React',           // The npm package react corresponds to the global variable React.
  'react-dom': 'ReactDOM',     // The npm package react-dom corresponds to the global variable ReactDOM.
  'antd': 'antd',             // The npm package antd corresponds to the global variable antd.
  'dayjs': 'dayjs',           // The npm package dayjs corresponds to the global variable dayjs.
}

Component directory structure

Each component must be in a separate folder within the src directory:

src/
└── ComponentName/          # Component directory
    ├── index.tsx          # Component implementation
    └── config.ts          # Component configuration

File descriptions:

• index.tsx: The React implementation code for the component.

• config.ts: The component's configuration for the low-code platform.

Component implementation (index.tsx)

Basic structure:

import React from 'react';
import { Button as AntdButton } from 'antd';

export interface ButtonProps {
  text?: string;
  type?: 'primary' | 'default';
  onClick?: () => void;
}

const Button: React.FC<ButtonProps> = ({
  text = 'Click',
  type = 'primary',
  onClick,
}) => {
  return (
    <AntdButton type={type} onClick={onClick}>
      {text}
    </AntdButton>
  );
};

export default Button;

Export requirements:

• ✅ Use export default to export the component.

• ✅ The component name should match the directory name.

• ❌ Anonymous exports are not supported.

Component configuration (config.ts)

Function: Defines the component's configuration in the low-code platform, including the properties panel, layout configuration, and metadata.

Basic structure:

const ButtonConfig = {
  // ========== Basic information ==========
  title: 'Custom Button',
  description: 'This is a button component',
  icon: 'https://xxx.jpg',
  category: 'Basic Components',
  
  // ========== Container related ==========
  isContainer: false,
  
  // ========== Properties panel configuration ==========
  inspectorConfig: [
    {
      title: 'Content',
      items: [
        {
          type: 'control',
          title: 'Button Text',
          name: 'text',
          defaultValue: 'Button',
          valueType: 'string',
          control: {
            type: 'Code',
            props: {},
          },
        },
      ],
    },
  ],
  
  // ========== Grid layout configuration ==========
  gridConfig: {
    dragRect: {
      w: 4,
      h: 32,
    },
    initHeight: () => ({ type: 'auto' }),
    supportHeightType: ['fixed', 'auto'],
  },
  
  // ========== Expose configuration ==========
  exposeConfig: {

    methods: [ ],

  },
};

export default ButtonConfig;

For more information about the configuration parameters, see Component configuration development specifications.

Create a component library

Use the mccl build command. A dist.zip file is generated in the project's root directory if you set outDir: 'dist' in the mobi.config.js file. Upload this dist.zip file to the Mobi platform for management.

Update a component library

Click Update in the Actions column for the component library you want to update. Enter the new version and update description. Then, upload the new version of the component library to update it.

Click View in the Actions column to see the release information for each version of the component library in the release history.

Note:

• When you update a component library, make sure its globalName remains unchanged.

Enable debug mode

Debug mode provides real-time previews during component library development. When you change your local code, the component on the canvas automatically updates. Debug mode is a temporary state. After you finish developing the component, disable debug mode. Then, build the component into a formal component library and upload it to the Mobi console for management and long-term use.

First, run mccl dev locally to enable debug mode.

Then, enable debug mode in the Mobi application by going to Settings > Component Library. When the name of the component library being debugged appears at the bottom of the page, the library is in debug mode. If you drag a component from this library onto the canvas, the component displays a "Debugging" label. When you modify the local component code, the component on the canvas updates automatically.