How to Create a Custom Plugin Component in Luban H5: A Complete Guide

To create a custom plugin component in Luban H5, scaffold a Vue component using the official vue-cli-plugin-lubanh5-component preset, implement your logic in component/index.js, optionally add a custom editor panel in component/editor.js, and register the plugin via the editor's plugin system.

Luban H5 is an open-source visual page builder that powers the ly525/luban-h5 repository. Extending the editor with custom plugin components allows you to add bespoke UI elements, business logic, or third-party integrations while maintaining full compatibility with the visual editing experience.

Scaffolding a New Plugin Component

The fastest way to create a custom plugin component in Luban H5 is using the official Vue CLI preset. This generates the required folder structure and boilerplate automatically.

Run the following command to scaffold your plugin:

vue create --preset luban-h5/vue-cli-plugin-lbhc my-luban-plugin
cd my-luban-plugin

The preset creates a standardized structure documented in docs/zh/plugin-development/quick-start.md【[quick-start.md](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/quick-start.md)】:

mini-editor/                 # simulated core editor environment

component/
  ├─ index.js               # component entry (Vue component)

  └─ editor.js                # optional editor-panel configuration

Implementing the Component Logic

A Luban H5 plugin component is fundamentally a standard Vue component. You write your logic in component/index.js, including props, methods, computed properties, and template syntax.

Default Injected Props

The editor automatically injects several default props into every plugin component, as documented in docs/zh/plugin-development/plugin-default-inject-props.md【[plugin-default-inject-props.md](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/plugin-default-inject-props.md)】. These include:

• editorMode: Distinguishes between 'edit' and 'preview' modes, allowing you to change behavior based on context.
• uuid: A unique identifier for the component instance.

Here is a complete example of component/index.js:

// component/index.js
export default {
  name: 'my-custom-button',
  props: {
    text: {
      type: String,
      default: 'Click me',
    },
    color: {
      type: String,
      default: '#409EFF',
      // The `editor` key tells Luban H5 which UI component to use in the property panel
      editor: {
        type: 'el-color-picker',
      },
    },
  },
  methods: {
    handleClick() {
      this.$emit('click');
    },
  },
  template: `
    <el-button
      :style="{ backgroundColor: color }"
      @click="handleClick"
    >{{ text }}</el-button>
  `,
};

Creating a Custom Editor Panel

When the default prop editors are insufficient, you can provide a custom editor panel. This is a Vue component that renders in the right-hand property panel when your plugin is selected.

Create component/editor.js (or component/editor.vue) as documented in docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md【[custom-editor-single-prop.md](https://github.com/ly525/luban-h5/blob/master/docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md)】:

// component/editor.js
export default {
  name: 'my-button-editor',
  props: {
    pluginProps: {
      type: Object,
      required: true,
    },
  },
  data() {
    return {
      localProps: { ...this.pluginProps },
    };
  },
  watch: {
    localProps: {
      deep: true,
      handler(val) {
        this.$emit('update:pluginProps', val);
      },
    },
  },
  template: `
    <div>
      <el-input v-model="localProps.title" placeholder="Card title" />
      <el-color-picker v-model="localProps.bgColor" />
    </div>
  `,
};

The core editor loads this through mini-editor/panel/props.js, rendering your custom UI whenever the component is active.

Registering and Distributing Your Plugin

The scaffolded project automatically handles registration through the plugin index system. The core registration logic resides in front-end/h5/src/plugins/index.js【[plugins/index.js](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/index.js)】, which imports:

• UI.js – UI-related mixins exposing editor utilities【[plugins/UI.js](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/UI.js)】
• Prototype.js – Vue prototype extensions for helper methods【[plugins/Prototype.js](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/plugins/Prototype.js)】
• components/global/index.js – global component registration that automatically loads custom plugins【[components/global/index.js](https://github.com/ly525/luban-h5/blob/master/front-end/h5/src/components/global/index.js)】

To distribute your plugin, build and publish to npm:

# Build the plugin package

yarn build

# Publish to npm (use --access public for scoped packages)

npm login
npm publish

Install the plugin in any Luban H5 project:

yarn add my-luban-plugin

The editor automatically discovers the plugin, injects default props, and makes the custom editor panel available without additional configuration.

Complete Working Example

Here is a minimal end-to-end example you can copy into a fresh scaffolded project.

Scaffold the project:

vue create --preset luban-h5/vue-cli-plugin-lbhc demo-plugin
cd demo-plugin

component/index.js:

export default {
  name: 'demo-card',
  props: {
    title: {
      type: String,
      default: 'Demo Card',
      editor: { type: 'el-input' },
    },
    bgColor: {
      type: String,
      default: '#FFFFFF',
      editor: { type: 'el-color-picker' },
    },
  },
  template: `
    <div :style="{ backgroundColor: bgColor, padding: '12px', border: '1px solid #ddd' }">
      <h3>{{ title }}</h3>
      <slot />
    </div>
  `,
};

component/editor.js (optional):

export default {
  name: 'demo-card-editor',
  props: { pluginProps: Object },
  data() {
    return { local: { ...this.pluginProps } };
  },
  watch: {
    local: {
      deep: true,
      handler(v) { this.$emit('update:pluginProps', v); },
    },
  },
  template: `
    <div>
      <el-input v-model="local.title" placeholder="Card title" />
      <el-color-picker v-model="local.bgColor" />
    </div>
  `,
};

Build and publish:

yarn build
npm publish

Install in another project:

yarn add demo-card

The component appears in the editor’s component palette automatically.

Summary

• Scaffold your plugin using vue create --preset luban-h5/vue-cli-plugin-lbhc to generate the required component/index.js and optional component/editor.js files.
• Implement the component as a standard Vue component in component/index.js, utilizing automatically injected props like editorMode and uuid.
• Configure the property panel by adding an editor field to props for simple cases, or create a full custom editor panel in component/editor.js for complex UIs.
• Register the plugin through the automatic global component system in front-end/h5/src/components/global/index.js.
• Distribute by building with yarn build and publishing to npm, then installing via yarn add in target projects.

Frequently Asked Questions

What is the difference between a plugin component and a regular Vue component in Luban H5?

A plugin component is a Vue component that follows the Luban H5 packaging convention, including the component/index.js entry point and optional component/editor.js for property panel customization. While regular Vue components can be used anywhere, plugin components receive automatic injections like editorMode and uuid, and integrate with the visual editor's property panel system as documented in plugin-default-inject-props.md.

How do I access the editor mode inside my custom plugin component?

The editor automatically injects the editorMode prop into every plugin component, distinguishing between 'edit' and 'preview' modes. You can use this prop to conditionally render editing controls or disable interactive features while in edit mode. This injection is handled by the core plugin system in front-end/h5/src/plugins/index.js and UI.js.

Can I use third-party UI libraries in my Luban H5 plugin?

Yes, you can import any UI library that Luban H5 already bundles, such as Element-UI, Ant-Design-Vue, or Vant. Since these libraries are already registered globally in the editor, you can use their components directly in your plugin's template without additional installation. For example, use <el-button> or <el-input> directly in your component/index.js template string.

What is the purpose of the editor.js file in a Luban H5 plugin?

The editor.js file provides a custom property panel UI for your plugin component. While simple props can use the inline editor configuration in index.js, complex components requiring coordinated multi-field editing or custom validation should export a Vue component from editor.js. This component receives the full pluginProps object and emits update:pluginProps to sync changes back to the main component, as implemented in mini-editor/panel/props.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}