nocobase-plugin-development

目標

要件分析から動作するコードの作成まで、NocoBase プラグインを開発する一連のプロセスを AI エージェントに案内し、NocoBase の規約に従い、すぐに有効化できるプラグインを作成します。

対象範囲

• ユーザー要件を分析し、NocoBase の拡張ポイントに対応付けます。
• nb scaffold plugin で新しいプラグインのひな形を作成します。
• サーバー側のコードを生成します。コレクション、ACL、カスタム API、マイグレーション、インストールフックが対象です。
• クライアント側のコードを生成します。ブロック、フィールド、アクション、設定ページ、ルートが対象です。
• i18n ロケールファイルを生成します。
• プラグインを有効化し、検証します。
• FAQ チェックリストとソースコード（利用可能な場合）を使って、よくある問題をトラブルシューティングします。

対象外

• UI を使った NocoBase アプリケーションの構築（これは nocobase-ui-builder の対象です）。
• 外部レジストリへのプラグイン公開。
• NocoBase のコアコードの変更。
• 既存プラグインのクライアント v1 から v2 への移行（これは nocobase-client-v2-plugin-migration の対象です）。

厳守事項

以下のルールは、生成するすべてのプラグインコードに適用されます。違反は常に誤りです。

this.app.use() または React Provider は絶対に使用しないでください

this.app.use() は内部 API です。プラグインで React Provider を使ってアプリをラップしてはいけません。これは推奨事項ではなく、例外のない厳守事項です。

Provider は不要な React レンダリング層を追加し、パフォーマンスを低下させ、プラグインの保守性を損ないます。ウォーターマーク、オーバーレイ、テーマ設定、トラッキング、グローバルリスナーなど、グローバルな効果を実装する場合は、代わりに次の方法を使用してください。

1. FlowEngine の仕組み（推奨） — UI 機能には registerModelLoaders、registerFlow、registerModels を使用します。
2. FlowEngine コンテキスト — this.context にはグローバルデータ（例：this.context.api、this.context.dataSourceManager、this.context.logger）が格納されています。データを受け渡すために Provider を作成せず、そこから直接読み取ってください。注：user、viewer、message、themeToken などのプロパティは React のレンダリング後にのみ利用できます。load() ではなく、フローハンドラーまたはコンポーネント内で使用してください。
3. API リクエスト — プラグインでデータが必要な場合は、this.app.apiClient.request() を使って直接取得してください。Axios インターセプターは使用できますが、最初の選択肢にすべきではありません。可能な場合は、直接リクエストするか、コンテキストから読み取る方法を優先してください。
4. 純粋な DOM 操作 — 視覚効果には、load() 内で DOM を直接操作してください。React コンポーネントは不要です。
5. EventBus — アプリのライフサイクルイベントへの対応には this.app.eventBus を使用します。

「このためには Provider が必要だ」と考えたら、いったん立ち止まって再検討してください。必ずもっと適切な方法があります。

クライアントコードは client-v2 のみに配置してください

クライアント側のプラグインコードはすべて src/client-v2/ に記述してください。src/client/ ディレクトリはレガシーの v1 クライアント用です。このディレクトリ内のファイルは作成も変更もしないでください。Plugin は必ず @nocobase/client-v2 からインポートし、@nocobase/client からはインポートしないでください。

モダンなクライアントは /v/ URL プレフィックスで動作します

client-v2/ ソースディレクトリは、実行時の /v/ URL プレフィックスに対応しています。ログイン後、ユーザーはデフォルトで /v/admin/ に移動します。アクセス先を案内するときは、/v/ の URL パターンを使用してください。

登録したもの	アクセス先
プラグインマネージャー、組み込みの管理ページ	/v/admin/
プラグイン設定ページ	/v/admin/settings/<menuKey>
this.router.add('xxx', { path: '/foo' }) によるカスタムルート	/v/foo（/v/admin/foo ではありません）

ユーザーが「プラグインを有効にしたのに何も表示されない」と言う場合や、404 が発生した場合、最もよくある原因は /v/admin/ ではなく /admin/... の URL にアクセスしていることです。前者はモダンなプラグインマネージャー（pm:listEnabledV2 を呼び出します）、後者は v1 のプラグインマネージャー（pm:listEnabled を呼び出します）です。/v/ の URL に切り替えるよう案内してください。

入力契約

入力	必須	デフォルト	検証	確認の質問
requirement	はい	なし	空でない自然言語による説明	「このプラグインには何をさせたいですか？」
nocobase_root	はい	現在の作業ディレクトリ	NocoBase のソースツリーを公開していること：CLI 管理の Git ソースアプリ（source/packages/core/ がある）または NocoBase ソースリポジトリ（packages/core/ がある）	「NocoBase のソースプロジェクトはどこにありますか？ プラグイン開発には、Git ソースインストールまたはクローンしたソースリポジトリが必要です。」
plugin_name	いいえ	要件から導出	@<scope>/plugin-<name> 形式	「プラグインのパッケージ名は何にしますか？」

ルール：

• nocobase_root が指定されていない場合は、現在の作業ディレクトリがソースツリーを含む NocoBase プロジェクトかどうかを確認します。
• ソースツリーのない NocoBase アプリ（Docker または npm インストール）の場合は、停止して Step 0 の選択肢を案内します。ソースツリーは必須であり、別の方法で代替することはできません。
• plugin_name が指定されていない場合は、要件から適切な名前を導出し、ユーザーに確認します。
• ユーザーが「お任せ」と言った場合は、文書化されたデフォルトを使用します。

必須の確認ゲート

• 確認ラウンドの上限：2
• 1 ラウンドあたりの質問数の上限：3
• 変更を行うための前提条件：
  • nocobase_root が NocoBase のソースツリー（CLI 管理の Git ソースアプリの場合は source/packages/core/、通常のソースリポジトリの場合は packages/core/）を公開しており、それぞれ nb CLI または yarn を使用できること。
  • requirement が、必要な拡張ポイントを判断できる程度に明確であること。
  • 機能計画が平易な言葉でユーザーに確認されていること。
• 2 ラウンドを経ても前提条件が満たされない場合は、停止して不足している内容を報告します。

重要：コードを作成したり、スキャフォールドコマンドを実行したりする前に、必ずユーザーに計画を確認してください。要件が完全に明確に見える場合でも例外はありません。 ユーザーには、明示されていない前提、考慮されていないエッジケース、スコープに関する希望があることがよくあります。計画の確認（Step 2）は必須のゲートであり、任意ではありません。決して省略しないでください。

ワークフロー

Step 0：環境チェック（必須ゲート — ソースコードが必要）

プラグイン開発には NocoBase のソースツリーが必要です。 スキャフォールディング、ビルド、デバッグはすべて、ソースリポジトリ内の packages/plugins/ を対象に行われます。ソースコードのない環境は使用できません。スキャフォールドを試みず、停止してユーザーに入手方法を案内してください。

1. 環境の種類を判別します：
   • CLI 管理のソースアプリ：source/ ディレクトリ（nb init によって作成）が存在します。ソースツリーは <app-path>/source/ にあります。source/packages/core/ の有無を確認し、Git ソースインストールであることを検証します。
   • 通常のソースリポジトリ：source/ はなく、packages/core/ が存在します。これはユーザー自身がクローンしたリポジトリ（git clone https://github.com/nocobase/nocobase.git）です。リポジトリのルートがソースツリーです。
   • どちらでもない場合 → 停止します。以下の「使用可能なソースツリーがない場合」を参照してください。
2. ツールチェーンを確認します：CLI 管理アプリでは nb CLI、通常のソースリポジトリでは yarn を使用します。
3. ソースツリーが完全であることを確認します。配下に packages/core/ が存在しなければなりません。これにより、トラブルシューティングのためにコアソースを読み取ることができ、ビルドに必要な依存関係も満たされます。

使用可能なソースツリーがない場合 — 停止してユーザーに伝える

作業ディレクトリが、source/ がDocker または npm によって配置された CLI 管理アプリ（source/packages/core/ がない）の場合、または NocoBase プロジェクトではない場合は、スキャフォールドを実行しないでください。状況を報告し、次の 2 つの選択肢を提示してください。

• Git ソースを使ってプロジェクトを作り直す — nb init --ui を実行し、ソースの選択画面で Git source install を選びます。プラグイン開発にはこちらを推奨してください。NocoBase のソース全体が <app-path>/source/ に配置されるため、プラグインをビルドでき、デバッグ時にコアソースを参照できます。他の 2 つの選択肢（Docker install、create-nocobase-app install）では、プラグイン開発に適したソースツリーは用意されません。

• 既存のソースリポジトリを指定する — ユーザーが別の場所に NocoBase のソースリポジトリをすでにクローンしている場合は、そのパスを尋ね、そこでプラグインを開発します。リポジトリがない場合は、次のコマンドでクローンできます。

  git clone https://github.com/nocobase/nocobase.git -b main --depth=1 my-nocobase
  cd my-nocobase && yarn install
  

ユーザーにどちらの選択肢を希望するか尋ねてください。代わりに選択せず、ソースツリーが用意されるまで先へ進まないでください。

CLI 管理のソースアプリでのコマンド実行ディレクトリ：

環境レベルのコマンドを除き、以下のすべてのコマンドはソースツリーに対して実行します。<app-path>/source/ から実行してください。

コマンド	実行場所
nb scaffold plugin	<app-path>/source/
nb source dev	<app-path>/source/
nb source build	<app-path>/source/
nb scaffold migration	<app-path>/source/
nb plugin enable/disable	任意のディレクトリ（環境レベルのコマンド）
nb app upgrade/restart	任意のディレクトリ（環境レベルのコマンド）

ステップ 1：要件の分析

ユーザーの要件を分析し、必要な拡張ポイントを判断してください。

• サーバー側：コレクション、カスタム REST API、ACL、cron ジョブ、マイグレーション、イベントリスナー
• クライアント側：ブロック（BlockModel/TableBlockModel）、フィールド（FieldModel）、アクション（ActionModel）、設定ページ、ルート
• 両方：サーバーデータとクライアント UI を備えたフルスタックプラグイン

ユーザーに技術的な詳細（例：「BlockModel と TableBlockModel のどちらが必要ですか？」）を尋ねないでください。要件を内部で拡張ポイントに対応付けてください。

ステップ 2：計画の確認（必須ゲート）

このステップは必須であり、要件がどれほど明確に見えても省略してはいけません。 一見単純な要件でも、ユーザーが伝えていないエッジケース、スコープの希望、前提条件がある可能性があります。ステップ 3 に進む前に、必ず計画を提示して明示的な承認を待ってください。

ユーザーに理解できる平易な言葉で、機能の計画を提示してください。ユーザーが検討していない可能性のある判断事項を、先回りして示してください（例：「プラグインを無効にした後もデータを保持しますか？」「設定用のページは必要ですか？」）。例：

「計画は次のとおりです。

1. API キーを設定できる設定ページを作成します
2. 5 分ごとにデータを同期するスケジュールタスクを追加します
3. 同期したレコードを保存するデータテーブルを作成します
4. UI でそのテーブルをブロックとして利用できるようにします

いくつか確認させてください。

• プラグインを無効にしたとき、同期データを消去しますか？
• 設定にアクセスできるユーザーを制御する権限が必要ですか？

この内容でよろしいですか？」

ユーザーが明示的に承認するまで、nb scaffold plugin を実行したり、コードを書いたりしてはいけません。

ステップ 3：プラグインをスキャフォールドする

どちらの環境でも、ソースツリーの packages/plugins/ にスキャフォールドされます。違いは、それをラップするコマンドだけです。

CLI で管理されるソースアプリの場合は、<app-path>/source/ から実行します。

cd <app-path>/source
nb scaffold plugin <plugin_name>
# Example: nb scaffold plugin @nocobase-sample/plugin-hello
# Creates:  <app-path>/source/packages/plugins/@nocobase-sample/plugin-hello/

nb scaffold plugin は pm create に処理を引き継ぎます。このコマンドは、常に現在の作業ディレクトリを基準に packages/plugins/ を生成先とするため、誤ったディレクトリから実行すると、プラグインも誤った場所に作成されます。使用できるフラグは --force-recreate のみです。

AI エージェント向けの注意： nb scaffold plugin は内部で、source/node_modules/.bin/ にある nocobase-v1 を呼び出します。サンドボックス環境や非対話型環境で、グローバルの nb が nocobase-v1 を自動的に見つけられない場合は、nb コマンドを実行する前に source/node_modules/.bin/ を PATH の先頭に追加する必要があることがあります。

PATH="<app-path>/source/node_modules/.bin:$PATH" nb scaffold plugin <plugin_name>

通常のソースリポジトリの場合は、リポジトリのルートから実行します。

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

create-plugin、generate、その他のバリエーションは使用しないでください。

スキャフォールド後、開発モードを起動すると、コードの変更がホットリロードされます。CLI で管理されるアプリでは <app-path>/source/ から nb source dev を、通常のソースリポジトリではリポジトリのルートから yarn dev を実行してください。

想定されるプロジェクト構造については、references/getting-started.md をお読みください。

ステップ 4：コードを生成する（必ず先にリファレンスを読む）

コードを書く前に、関連するリファレンスファイルを必ず読んでください。 ソースコードを検索する、サンプルを読む、または既存の知識に頼ることで、これを省略してはいけません。リファレンスには、このプロジェクト固有の規約が記載されており、一般的な知識よりも優先されます。

references/index.md を読んで関連するリファレンスファイルを確認し、このプラグインに必要なファイルを読んでください。

必須のリファレンスルール

これらは提案ではなく、必ず守るべき要件です。該当するコードを編集する前に、対象のファイルを読んでください。

編集する箇所	先に必ず読むファイル
src/client-v2/plugin.tsx	references/client/plugin.md
src/server/plugin.ts	references/server/plugin.md
src/client-v2/models/ 内のファイル	該当するものとして、references/client/block.md、references/client/field.md、または references/client/action.md
src/server/collections/ 内のファイル	references/server/collection.md

キーワードに応じて読むリファレンス

実装に以下の概念が含まれる場合は、対応するリファレンスも必ず読んでください。

コード内のキーワード	必ず読むファイル
route、router、navigate、location、pathname	references/client/router.md および references/client/ctx.md
ctx.api、ctx.viewer、ctx.message、ctx.model	references/client/ctx.md
registerFlow、uiSchema、on: イベントハンドラー	references/client/flow.md
resource、MultiRecordResource、SingleRecordResource	references/client/resource.md
標準フロントエンドの表示・編集用に保持されるフィルター	nocobase-utils をトピック filter で読み込み、該当するクライアント／サーバーのリファレンスに加えて、フィルター条件の形式を読む
tExpr、useT、this.t	references/client/i18n.md
acl.allow、パーミッション	references/server/acl.md
defineCollection、フィールド、リレーション	references/server/collection.md

生成の順序

プラグインの要件に合わせて柔軟に調整してください。

• データテーブルと API があるプラグインでは、サーバー側から始めます。
• フロントエンドのみのプラグインでは、クライアント側から始めます。
• 両側が密接に連携する場合は、交互に進めます。

クライアントコードを書く前のチェックポイント：「厳守事項」のセクションを確認してください。this.app.use() や Providers は決して使用しないでください。代わりに FlowEngine、コンテキスト、純粋な DOM、または EventBus を使用してください。

ステップ 5：国際化

デフォルトの動作（質問しないでください）：

• 必ず src/locale/zh-CN.json と src/locale/en-US.json を生成します。
• src/client-v2/locale.ts を作成します（スキャフォールドでは生成されません）。そこから tExpr / useT をインポートします。内容については references/client/i18n.md を参照してください。

追加の言語について質問するのは、次の場合に限ります：

• ユーザーが他の言語に明示的に言及した場合、または
• ユーザーが中国語または英語以外の言語でやり取りしている場合。

ステップ 6：有効化と確認

CLI 管理対象のソースアプリの場合：

nb plugin enable <plugin_name>

通常のソースリポジトリの場合：

yarn pm enable <plugin_name>

有効化した後、UI に何が表示されるか、プラグインをどうテストするかを説明してください。ユーザーに URL を引用するときは、必ず /v/ プレフィックスを使用してください（例：/v/admin/、/v/admin/settings/<menuKey>、/v/<custom-path>）。ハード制約の「最新クライアントは /v/ URL プレフィックスで動作する」ルールを参照してください。

デフォルトの動作

ユーザーから明示的な指定がない限り、以下のデフォルトを適用します。これらについて質問しないでください。

決定事項	デフォルト	質問する場合
クライアントのバージョン	client-v2 のみ。すべてのクライアントコードは src/client-v2/ に配置します。src/client/ は使用せず、@nocobase/client からもインポートしません	なし
モデルの登録	registerModelLoaders（遅延読み込み）	なし
ルートの登録	componentLoader（遅延読み込み）	なし
設定ページの登録	componentLoader を使った pluginSettingsManager.addMenuItem() + addPageTabItem()	なし
ACL	acl.allow('*', '*', 'loggedIn')	ユーザーがきめ細かな権限に言及した場合
ロケールファイル	zh-CN.json + en-US.json	ユーザーが他の言語に言及した場合
addCollection（クライアント側）	追加しないでください。代わりに UI の「Data Source Management」を推奨します	デモの場合のみ。必要であれば eventBus パターンを使用します（load() から直接呼び出さないでください）
install() のシードデータ	追加しないでください	ユーザーがプリセット／デモデータに言及した場合
tExpr のインポート	プラグインの locale.ts からインポートします。@nocobase/flow-engine から直接インポートしません	なし
this.app.use()（Provider）	使用しないでください。代わりに FlowEngine の仕組み、または純粋な DOM を使用します。client/plugin.md を参照してください	なし

トラブルシューティング

プラグインが期待どおりに動作しない場合：

FAQ チェックリスト

1. プラグインがプラグインマネージャーに表示されない → 次の順に確認します：（a）ブラウザーの URL は /admin/... ではなく /v/admin/ である必要があります。v2 プラグインを取得して表示するのは最新のプラグインマネージャーのみで、取得には pm:listEnabledV2 を使用します。（b）プラグインが nb plugin enable <name>（CLI 管理対象アプリ）または yarn pm enable <name>（通常のソースリポジトリ）で有効化されていること。（c）package.json に正しい NocoBase メタデータが含まれていること。
2. コレクションがブロック選択画面に表示されない → NocoBase UI の「Data Source Management」からテーブルを追加するようユーザーに推奨してください。コードレベルでの登録が必要な場合（デモのみ）は、filterTargetKey: 'id' を指定した addCollection と eventBus パターンを使用します。client/plugin.md を参照してください。
3. 設定ページが空白になる → client-v2 では Component ではなく componentLoader を使用していることを確認してください。
4. モデルがメニューに表示されない → プラグインの load() に define({ label: tExpr('...') }) と registerModelLoaders があることを確認してください。
5. load() のデータベースクエリが失敗する → load() は DB 同期の前に実行されます。DB 操作を install() またはリクエストハンドラーに移してください。
6. i18n が機能しない → 初回のロケールファイル追加後は、アプリの再起動が必要です。tExpr が @nocobase/flow-engine ではなく locale.ts からインポートされていることを確認してください。
7. registerFlow ハンドラーが起動しない → on イベント名を確認してください。ボタンには 'click'、初期化には 'beforeRender' を使用します。

ソースコードのデバッグ

ステップ 0 でソースツリーが保証されているため、デバッグ時にはコアソースをいつでも確認できます。API の挙動を推測するのではなく、ソースを読んでください。

CLI 管理対象の Git ソースアプリの場合：

source/packages/core/server/src/          — Server core
source/packages/core/client-v2/src/       — Client core (v2, recommended)
source/packages/core/database/src/        — Database layer
source/packages/core/flow-engine/src/     — FlowEngine

通常のソースリポジトリの場合：

packages/core/server/src/                 — Server core
packages/core/client-v2/src/              — Client core (v2, recommended)
packages/core/database/src/               — Database layer
packages/core/flow-engine/src/            — FlowEngine

完全なプラグインの例

完全に動作する例が必要な場合は、ローカルのソースツリーからサンプルプラグインを確認してください。

• CLI 管理の Git ソースアプリ：source/packages/plugins/@nocobase-example/
• 通常のソースリポジトリ：packages/plugins/@nocobase-example/
• ローカルのチェックアウトに存在しない場合は、https://github.com/nocobase/nocobase/tree/develop/packages/plugins/%40nocobase-example/ を参照してください。

リファレンスの読み込みマップ

リファレンス	使用するタイミング	備考
references/index.md	常に、ステップ 1 の後	グローバルインデックスです。関連するモジュールのリファレンスを探すために参照してください。
references/getting-started.md	ステップ 3（スキャフォールディング）	プラグインのスキャフォールドとプロジェクト構成
references/server/*.md	プラグインにサーバーサイドのコードが必要な場合	サーバーモジュールごとに 1 ファイル
references/client/*.md	プラグインにクライアントサイドのコードが必要な場合	クライアントモジュールごとに 1 ファイル
references/build.md	ユーザーがビルドやパッケージ化について質問した場合	ビルドと配布

安全確認

影響の大きい操作：

• nb scaffold plugin / yarn pm create の実行（ユーザーのプロジェクトにファイルを作成します）
• nb plugin enable / yarn pm enable の実行（データベースの状態を変更します）
• 既存のプラグインファイルの変更（プラグインがすでに存在する場合）

二次確認のテンプレート：

• 「{{directory}} で {{command}} を実行しようとしています。これは {{impact}} します。続行してもよろしいですか？」

ロールバックのガイダンス：

• nb scaffold plugin で誤ったスキャフォールドが生成された場合 → 生成されたディレクトリを削除して、再実行してください。
• 有効化後にプラグインのコードにバグがある場合 → コードを修正してください。nb plugin disable <name> でプラグインを無効にできます。
• 明示的なユーザー確認なしに nb app upgrade --force または yarn nocobase install -f を実行しないでください。データベースがリセットまたは変更される可能性があります。

検証チェックリスト

• NocoBase のソースツリー（source/packages/core/ または packages/core/）と、適切な CLI（nb または yarn）を利用できます。どちらも利用できない場合、ステップ 0 で処理を停止し、ユーザーに 2 つの選択肢を提示します。
• 環境の種類（CLI 管理の Git ソースアプリか、通常のソースリポジトリか）を判別し、スキャフォールドとビルドのコマンドをソースツリーから実行しました。
• ユーザーの要件を分析し、拡張ポイントを特定しました。
• コードを生成する前に、機能計画についてユーザーの確認を得ました。
• プラグインのスキャフォールドが正常に作成されました。
• 生成されたすべてのファイルが NocoBase の規約（client-v2、遅延読み込み、locale.ts）に従っています。
• 生成されたコードに this.app.use() や React Provider のパターンがありません（厳守事項）。
• 翻訳可能な文字列をすべて含む zh-CN.json と en-US.json が生成されました。
• エラーなく nb plugin enable（通常のソースリポジトリでは yarn pm enable）でプラグインを有効化できます。
• 生成されたコードがリファレンステンプレートのパターンに一致しています。
• 問題が発生した場合に FAQ チェックリストを参照しました。

最小テストシナリオ

1. ユーザーがシンプルな設定ページのプラグインを依頼する → スキャフォールド + サーバー API + クライアント設定ページ。
2. ユーザーがカスタムブロックプラグインを依頼する → スキャフォールド + BlockModel + registerFlow + i18n。
3. ユーザーがフルスタック CRUD プラグインを依頼する → スキャフォールド + defineCollection + ACL + TableBlockModel + カスタムフィールド + カスタムアクション。
4. ユーザーの要件が曖昧 → 確認プロセスを開始し、コーディング前に計画について確認を得る。
5. プラグインの有効化に失敗する → FAQ チェックリストを参照し、利用可能な場合はソースコードを確認する。
6. ユーザーが Docker または npm でインストールしたアプリでスキルを実行する（ソースツリーなし） → ステップ 0 でスキャフォールディング前に停止し、nb init --ui + Git source install でプロジェクトを再作成するか、既存のソースリポジトリを指定する方法を提示する。

出力の要件

最終回答には、次の内容を含める必要があります。

• 依頼内容（ユーザーの当初の要件）。
• 作成したもの（生成されたファイルの一覧）。
• 有効化とテストの方法（コマンド + 期待される UI の動作）。
• 適用した前提条件やデフォルト設定。
• 既知の制限事項または次のステップ（該当する場合）。

参考資料

• 参考資料インデックス：すべての参考資料ファイルのグローバルインデックスです。
• はじめに：プラグインのひな形とプロジェクト構成です。
• オンラインドキュメント — プラグイン開発：プラグイン開発に関する完全なドキュメントです。[検証日：2026-04-10]
• オンラインドキュメント — FlowEngine：FlowEngine の完全なリファレンスです。[検証日：2026-04-10]
• プラグインの例（GitHub）：動作するプラグインの例です。[検証日：2026-04-10]