Step-by-step playbook for developing a NocoBase plugin, covering scaffolding, server-side code (collections, APIs, ACL, migrations), client-side code (blocks, fields, actions, settings pages, routes, components), i18n, and verification.
TRIGGER when: user asks to create, build, implement, or develop a NocoBase plugin, mentions 'NocoBase plugin', or describes a feature to be built as a NocoBase plugin. This skill contains NocoBase-specific conventions and templates that general coding cannot replicate — always invoke it instead of planning from scratch.
Step-by-step playbook for developing a NocoBase plugin, covering scaffolding, server-side code (collections, APIs, ACL, migrations), client-side code (blocks, fields, actions, settings pages, routes, components), i18n, and verification.
TRIGGER when: user asks to create, build, implement, or develop a NocoBase plugin, mentions 'NocoBase plugin', or describes a feature to be built as a NocoBase plugin. This skill contains NocoBase-specific conventions and templates that general coding cannot replicate — always invoke it instead of planning from scratch.
when_to_use
Trigger when: user mentions "NocoBase plugin", or asks to create/build/implement/develop
a plugin for NocoBase, or describes a feature that should be built as a NocoBase plugin
(e.g. "watermark plugin", "export plugin", "approval plugin").
Example requests:
- "Help me implement a NocoBase watermark plugin"
- "Create a plugin that adds a settings page"
- "Build a NocoBase plugin for data export"
- "Develop a custom block plugin"
Guide an AI agent through the complete process of developing a NocoBase plugin — from requirement analysis to working code — producing a plugin that follows NocoBase conventions and can be enabled immediately.
Scope
Analyze user requirements and map them to NocoBase extension points.
Troubleshoot common issues using FAQ checklist and source code (when available).
Non-Goals
Do not build NocoBase applications through the UI (that's nocobase-ui-builder).
Do not handle plugin publishing to external registries.
Do not modify NocoBase core code.
Do not migrate existing plugins from client v1 to v2 (that's nocobase-client-v2-plugin-migration).
Hard Constraints
These rules apply to ALL generated plugin code. Violating them is always wrong.
NEVER use this.app.use() or React Providers
this.app.use() is an internal API. Plugins must NEVER use it to wrap the app with React providers. This is not a suggestion — it is a hard rule with no exceptions.
Providers add unnecessary React rendering layers, hurt performance, and make plugins harder to maintain. When implementing global effects (watermarks, overlays, theming, tracking, global listeners, etc.), use these approaches instead:
FlowEngine mechanisms (preferred) — registerModelLoaders, registerFlow, registerModels for UI capabilities.
FlowEngine context — this.context holds global data (e.g., this.context.api, this.context.dataSourceManager, this.context.logger). Read from it directly instead of creating Providers to pass data around. Note: some properties like user, viewer, message, themeToken are only available after React renders — use them in flow handlers or components, not in load().
API requests — if the plugin needs data, use this.app.apiClient.request() to fetch it directly. Axios interceptors are allowed but should not be the first choice — prefer direct requests or reading from context when possible.
Pure DOM manipulation — operate on the DOM directly in load() for visual effects. No React component needed.
EventBus — this.app.eventBus for reacting to app lifecycle events.
If you find yourself thinking "I need a Provider for this", stop and reconsider. There is always a better alternative.
Client code goes in client-v2 ONLY
All client-side plugin code must be written in src/client-v2/. The src/client/ directory is for the legacy v1 client — do NOT write or modify any files there. Import Plugin from @nocobase/client-v2, never from @nocobase/client.
v2 mode runs under the /v2/ URL prefix
The client-v2/ source directory corresponds to the /v2/ runtime URL prefix. After login, users land on /v2/admin/ by default. When telling users where to access something, use the v2 URL pattern:
What you registered
Accessible at
Plugin manager, built-in admin pages
/v2/admin/
Plugin settings pages
/v2/admin/settings/<menuKey>
Custom routes via this.router.add('xxx', { path: '/foo' })
/v2/foo (NOT /v2/admin/foo)
If the user says "I enabled the plugin but nothing shows up" or hits a 404, the most common cause is they are on a /admin/... URL (v1 plugin manager, which calls pm:listEnabled) instead of /v2/admin/ (v2 plugin manager, which calls pm:listEnabledV2). Tell them to switch to the /v2/ URL.
Input Contract
Input
Required
Default
Validation
Clarification Question
requirement
yes
none
non-empty natural language description
"What should this plugin do?"
nocobase_root
yes
current working directory
must contain package.json with @nocobase/server
"Where is your NocoBase project root directory?"
plugin_name
no
derived from requirement
@<scope>/plugin-<name> format
"What should the plugin package name be?"
Rules:
If nocobase_root is not provided, check if the current working directory is a NocoBase project.
If plugin_name is not provided, derive a reasonable name from the requirement and confirm with the user.
If user says "you decide", use documented defaults.
Mandatory Clarification Gate
Max clarification rounds: 2
Max questions per round: 3
Mutation preconditions:
nocobase_root is a valid NocoBase project with yarn available.
requirement is clear enough to determine which extension points are needed.
Functional plan has been confirmed by the user in plain language.
If preconditions are not met after two rounds, stop and report what's missing.
CRITICAL: You MUST always confirm the plan with the user before writing any code or running any scaffold command — even if the requirement seems perfectly clear. Users often have unstated assumptions, edge cases they haven't considered, or preferences about scope. The plan confirmation step (Step 2) is a hard gate, not a suggestion. Never skip it.
Workflow
Step 0: Environment Check
Verify nocobase_root contains a valid NocoBase project (package.json with @nocobase/server).
Verify yarn is available.
Detect environment type:
Source install: packages/core/ exists → AI can read source code for troubleshooting.
create-nocobase-app: no packages/core/ → rely on documentation and online references only.
Step 1: Requirement Analysis
Analyze the user's requirement and determine which extension points are needed:
Both: full-stack plugins with server data + client UI
Do NOT ask the user about technical details (e.g., "Do you need a BlockModel or TableBlockModel?"). Map requirements to extension points internally.
Step 2: Plan Confirmation (HARD GATE)
This step is mandatory and must not be skipped, regardless of how clear the requirement appears. Even seemingly straightforward requirements can have unstated edge cases, scope preferences, or assumptions the user hasn't mentioned. Always present the plan and wait for explicit confirmation before proceeding to Step 3.
Present a functional plan in plain language the user can understand. Proactively highlight decisions the user may not have considered (e.g., "Should the data persist after plugin disable?", "Do you need a settings page for configuration?"). Example:
"Here's my plan:
Create a settings page where you can configure the API key
Add a scheduled task that syncs data every 5 minutes
Create a data table to store the synced records
The table will be available as a block in the UI
A few things to confirm:
Should the synced data be cleared when the plugin is disabled?
Do you need permission control for who can access the settings?
Does this look right?"
Do NOT run yarn pm create or write any code until the user explicitly confirms.
You MUST read the relevant reference files BEFORE writing any code. Do NOT skip this by searching source code, reading examples, or relying on prior knowledge. The references contain project-specific conventions that override general knowledge.
Read references/index.md to locate the relevant reference files, then read the ones needed for this plugin.
Mandatory Reference Rules
These are hard gates, not suggestions. Read the file BEFORE editing the corresponding code:
When you edit...
You MUST first read
src/client-v2/plugin.tsx
references/client/plugin.md
src/server/plugin.ts
references/server/plugin.md
Any file in src/client-v2/models/
references/client/block.md, references/client/field.md, or references/client/action.md (whichever applies)
Any file in src/server/collections/
references/server/collection.md
Keyword-Triggered References
If your implementation involves any of these concepts, you MUST also read the corresponding reference:
Keywords in your code
MUST read
route, router, navigate, location, pathname
references/client/router.md and references/client/ctx.md
Server-first when the plugin has data tables and APIs.
Client-first when the plugin is purely frontend.
Interleaved when both sides are tightly coupled.
Checkpoint before writing client code: Review the "Hard Constraints" section. Never use this.app.use() or Providers. Use FlowEngine, context, pure DOM, or EventBus instead.
Step 5: Internationalization
Default behavior (do NOT ask):
Always generate src/locale/zh-CN.json and src/locale/en-US.json.
Use the plugin's auto-generated locale.ts for tExpr and useT imports.
Only ask about additional languages if:
The user explicitly mentions other languages, OR
The user is communicating in a language other than Chinese or English.
Step 6: Enable and Verify
yarn pm enable <plugin_name>
After enabling, describe what the user should see in the UI and how to test the plugin. When quoting URLs to the user, always use the /v2/ prefix (e.g., /v2/admin/, /v2/admin/settings/<menuKey>, /v2/<custom-path>) — see the "v2 mode runs under the /v2/ URL prefix" rule under Hard Constraints.
Default Behaviors
These defaults apply unless the user explicitly requests otherwise. Do NOT ask about them.
Decision
Default
When to ask
Client version
client-v2 ONLY. All client code in src/client-v2/. Never use src/client/ or import from @nocobase/client
Never
Model registration
registerModelLoaders (lazy loading)
Never
Route registration
componentLoader (lazy loading)
Never
Settings page registration
pluginSettingsManager.addMenuItem() + addPageTabItem() with componentLoader
Never
ACL
acl.allow('*', '*', 'loggedIn')
User mentions fine-grained permissions
Locale files
zh-CN.json + en-US.json
User mentions other languages
addCollection (client-side)
Do NOT add — recommend UI "Data Source Management" instead
Only as a demo; if needed, use eventBus pattern (NOT direct call in load())
install() seed data
Do NOT add
User mentions preset/demo data
tExpr import
From plugin's locale.ts, NOT from @nocobase/flow-engine directly
Never
this.app.use() (Provider)
Do NOT use — use FlowEngine mechanisms or pure DOM instead. See client/plugin.md
Never
Troubleshooting
When the plugin doesn't work as expected:
FAQ Checklist
Plugin not appearing in plugin manager → In order: (a) browser URL must be /v2/admin/, not /admin/... — only the v2 plugin manager fetches via pm:listEnabledV2 and shows v2 plugins; (b) plugin has been enabled with yarn pm enable <name>; (c) package.json has correct NocoBase metadata.
Collection not showing in block picker → Recommend user to add the table via NocoBase UI "Data Source Management". If code-level registration is needed (demo only), use addCollection with filterTargetKey: 'id' and eventBus pattern. See client/plugin.md.
Settings page shows blank → Verify using componentLoader (not Component) for client-v2.
Model not appearing in menus → Check define({ label: tExpr('...') }) and registerModelLoaders in plugin load().
load() database query fails → load() runs before DB sync. Move DB operations to install() or request handlers.
i18n not working → First-time locale files require app restart. Check tExpr is imported from locale.ts not @nocobase/flow-engine.
registerFlow handler not firing → Check on event name. Use 'click' for buttons, 'beforeRender' for initialization.
Source Code Debugging (Source Install Only)
If the environment is a source install, the AI agent may read NocoBase core source code to debug issues:
