nocobase-plugin-development

What this skill does

# Goal

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.
- Scaffold a new plugin with `yarn pm create`.
- Generate server-side code: collections, ACL, custom APIs, migrations, install hooks.
- Generate client-side code: blocks, fields, actions, settings pages, routes.
- Generate i18n locale files.
- Enable and verify the plugin.
- 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:

1. **FlowEngine mechanisms** (preferred) — `registerModelLoaders`, `registerFlow`, `registerModels` for UI capabilities.
2. **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()`.
3. **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.
4. **Pure DOM manipulation** — operate on the DOM directly in `load()` for visual effects. No React component needed.
5. **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

1. Verify `nocobase_root` contains a valid NocoBase project (`package.json` with `@nocobase/server`).
2. Verify `yarn` is available.
3. 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:

- **Server-side**: collections, custom REST APIs, ACL, cron jobs, migrations, event listeners
- **Client-side**: blocks (BlockModel/TableBlockModel), fields (FieldModel), actions (ActionModel), settings pages, routes
- **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:
> 1. Create a settings page where you can configure the API key
> 2. Add a scheduled task that syncs data every 5 minutes
> 3. Create a data table to store the synced records
> 4. 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.**

## Step 3: Scaffold Plugin

The exact command is:

```bash
yarn pm create <plugin_name>
# Example: yarn pm create @nocobase-sample/plugin-hello
# Creates:  packages/plugins/@nocobase-sample/plugin-hello/
```

This is the only correct command. Do NOT use `create-plugin`, `generate`, or any other variant. Do NOT look up alternatives — just run it.

Read `references/getting-started.md` for the expected project structure.

## Step 4: Generate Code (MUST Read References First)

**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 o