nocobase-app-plugin-development

NocoBase プラグイン開発

NocoBase 3 リポジトリでプラグインのソースを開発する際に、このスキルを使用します。編集する前に、該当する AGENTS.md を読み、対象のプラグインと App を確認してください。ワークスペースに packages/tools/create-plugin/、packages/app/app-client/、packages/app/app-server/、および pnpm-workspace.yaml が含まれていることを確認してください。packages/plugins/ ディレクトリがあるだけでは v3 とは判断できません。この環境では、従来の Plugin クラス、src/client-v2/、または nb scaffold plugin の手順を適用しないでください。

該当するリファレンスを選択する

以下の英語リファレンスでは、プラグイン開発ガイドをタスク固有の手順にまとめています。タスクに関連する行を読み、デフォルトではリファレンス全体を読み込まないでください。

タスク	参照
プラグインの作成、機能の選択、宣言、エクスポート、依存関係、または公開コントラクトの変更	スキャフォールディングとパッケージコントラクト
プラグイン統合の登録、設定、アップグレード、無効化、登録解除、または診断	登録とライフサイクル
Client コンポーネント、ServiceProvider、React Provider、設定、または API アクセスの選択	Client アーキテクチャ
Server の設定デフォルト、環境マッピング、検証、またはブラウザーに表示されるフィールドの定義	プラグイン設定
プラグイン UI の構築または変更	shadcn コンポーネントとスタイル設定
ビジネスページ、メニュー、Tabs、ルートダイアログ／ドロワー、子ルート、またはページオーバーライドの追加	Client ルーティング
設定エンティティ、設定権限、ルーティングされたエディター、安全な保存の設計	システム設定
サービスコントラクト、Token、依存性注入、またはライフサイクルの定義	サービスと Provider
HTTP エンドポイント、認可、Repository 操作、バックグラウンドジョブ、またはキューの追加	Server 開発
/api パスの命名、メソッドの選択、レスポンスまたはエラーの形式、入力の検証	HTTP API のルール
マイグレーション、シード、またはパッケージのリソース／チェックサム処理の追加	データベースリソース
テキスト、ロケールリソース、翻訳済みエラー、または受信者の言語でのメッセージの追加・変更	国際化
App が所有する編集可能な Client ソースの作成、公開、インストール、アップグレード、または削除	レジストリ
プラグインの機能を App Agent に公開	プラグインスキル
コマンド、CLI エクスポート、または CLI 登録の追加	CLI プラグイン
@nocobase/app-testing を使用したデータベース、Server、Client、または CLI のテストと App 統合の検証	テストとデリバリー
マイグレーション、保護された API、Client、設定、CLI テストを含む、実行可能なプラグインを一通り確認	テストの完全な例

Realtime の変更については、対象のワークスペースまたはアプリケーションに、@nocobase/realtime のバージョンが一致する nocobase-realtime Skill があるか確認し、インストール済みの API 宣言と併せて参照してください。パッケージ統合のガイダンスは、対象ランタイムのバージョンに合致している必要があります。 実装例とテストについては、該当するサーバールートの例、ServiceToken と Provider の例、クライアントの例、またはリポジトリの例を参照してください。これらはトピック別のリファレンスを具体的なコードで補足し、保守されているソースフィクスチャを示しています。明示されている例のアクセス方針は、対象の製品に合わせて調整してください。

実装前に適用するルール

ページを作成する場合やページコンポーネントを記述する場合は、ページコンポーネントの構造とルート宣言について、ページ、ルート、メニューを参照してください。ネストされたページ、ページレベルのナビゲーションタブ、ルートダイアログ／ドロワー、またはナビゲーショングループについては、子ルート、タブ、オーバーレイ、ナビゲーショングループ、Outletも参照してください。ページとオーバーレイの例を使用する前に、必要なコンポーネントソースをプラグインにコピーしてください。例では、ホストの非公開パンくずコンポーネントを除き、プラグインが所有するこれらのコピーを相対 .js パスでインポートしています。ルートオーバーレイコンポーネントの利用可否とフックのコンテキスト境界については、ルートダイアログとドロワーを参照してください。

• ボタン、入力フィールド、ダイアログ、セレクト、Tabs など、インタラクティブな UI プリミティブには shadcn コンポーネントを使用してください。UI の作業に取りかかる前に、コンポーネントのリファレンスを確認してください。プラグインが所有するコンポーネントはプラグイン内に置き、components.json をパッケージ内の # インポートおよび公開される dist マッピングに合わせてください。色、タイポグラフィ、間隔、サイズ、角丸、シャドウには共有テーマトークンを使用してください。
• ページレベルのナビゲーション Tabs には、ユーザーがルーティングに言及していない場合も、デフォルトで子ルートを使用してください。各 Tab のコンテンツを子ルートとして宣言し、親ページコンポーネントで Outlet をレンダリングして、URL からアクティブな Tab を判定してください。親 URL が子ルートなしで開かれた場合は、現在の履歴エントリを置き換え、クエリパラメーターを保持して、デフォルトのアクセシブルな Tab にリダイレクトしてください。明示的な Tab の URL を開いた場合は、その Tab の選択状態を保持してください。操作方法についてユーザーから明示的な指定がある場合は、それに従ってください。
• pnpm plugin:create と明示的な機能を使ってプラグインを作成してください。必要に応じて cli も含めてください。--dry-run --json でプレビューしてください。生成されたランタイム対応の共有開発設定を維持してください。
• 宣言は静的にし、起動時の副作用を発生させないでください。ページコンポーネント、ロケールメッセージ、大型 SDK、本当に任意の機能は、それぞれの末端境界で遅延読み込みしてください。ページは Routes、コンポーネントは公開／ソースエクスポートであり、いずれも独立したランタイムローダーではありません。
• すべてのプラグインの文言を、すべての Client および Server ロケールマニフェストで、対応する10言語（en-US、zh-CN、zh-TW、ja-JP、es-ES、pt-BR、fr-FR、de-DE、vi-VN、id-ID）に翻訳してください。型は en-US のリソース全体に基づいて指定してください。プラグインが依存するライブラリも、@nocobase/app-plugin-i18n における @nocobase/i18n のように翻訳を含む場合は、同様に10言語すべてに対応させてください。新規または変更されたキーは、同じ変更内で10言語すべてに翻訳してください。アプリケーションテンプレートは対象外です。
• ホストの API クライアントを useApiClient() または apiClientToken 経由で再利用してください。別のアプリケーション API クライアントを構築しないでください。実装に先立ち、共有サービスの契約と所有元が作成する Token を定義してください。利用側は元の Token をインポートしてください。
• プラグインは設定ページや開発ページを追加しません。Client のルート API は defineAppRoutes() のみです。管理機能は設定項目と API として公開し、管理領域ごとにグループ化してください（例：Automation には Workflow と Schedules を含めます）。それらを表示するページはアプリケーションに任せてください。宣言とサーバー操作の境界については、システム設定を参照してください。
• すべての /api ルートはHTTP API のルールに従ってください。プラグインの名前空間内で camelCase のパスを使用し、標準メソッドを使い、{ data } 形式でレスポンスを返し、すべての失敗で ApiError を使用してください（クライアントは reason に基づいて分岐します）。入力は zod で定義し、apiValidator() で検証してください。アプリケーションの /api/swagger/docs OpenAPI ドキュメントに含めるため、すべてのルートに describeRoute() の宣言を記述してください。データエンドポイントは POST /api/{name}/{action} とし、camelCase の公開名を使用します。これらは宣言を使わずにドキュメント化してください。
• 各 Server Route は、自身の認証と認可、または明示的な公開プロトコルの境界を所有し、テストしてください。他のコントリビューションのミドルウェアや登録順序は保護になりません。createRouter() を通じて本番のコントリビューションをテストしてください。
• すべての Server プラグインで絶対パスの baseDir を宣言してください。マイグレーション、シード、Jobs はこのパスを基準に解決し、コンパイル済みプラグインがコンパイル済みリソースを使用できるようにしてください。マイグレーションは明示的かつ自己完結型とし、マージ後は不変にして、実際のデータベースに対してテストしてください。
• プラグインのテストフィクスチャは devDependencies に宣言した @nocobase/app-testing/server、/client、または /cli から取得してください。環境の選択、本番プラグインの登録、データベースとストレージの分離には、テストディレクトリとフィクスチャのガイドを参照してください。
• 対応するターゲット App のコンポジションルートに、Client、Server、CLI のエクスポートを明示的に登録してください。インストール、登録、Skills の同期、ランタイムの動作は、それぞれ別の事実です。レガシーのマニフェストメタデータは、ランタイムでの検出には使われません。
• プラグインの統合に関する知識は <plugin>/skills/ に記述します。ターゲット App の .agents/skills/ は生成される出力です。App にコピーされたレジストリソースは、その App に属します。このリポジトリの開発 Skill は、どちらの種類の出力とも異なる、保守対象のソースです。
• リポジトリの依存関係ルールに従ってください。共有ランタイムとクライアントの値インポートはピア依存関係、通常のサーバーランタイムインポートは dependencies、開発時のみのインポートは devDependencies とします。公開される宣言に残す型参照には、利用側から解決可能な契約が必要です。

実装ワークフロー

1. 作業ツリーの変更、プラグインのマニフェスト、宣言、エクスポート、テスト、対象の App を確認します。要求された動作と、そのデータ、UI、サービス、統合コードの担当箇所を特定します。
2. 必要な機能を選び、最小限の公開コントラクトを定義します。Client のオプション／エクスポート、Server の Tokens／API、CLI コマンド、権限／エラーの境界、観測可能な結果などが含まれます。上記のうち、関連するリファレンスのみを使用します。
3. 担当するプラグインに実装します。ドメインの動作は Services に、HTTP の境界は Routes に、非同期のオーケストレーションは Jobs に、React のコンテキストは React Providers に、アプリケーションへの統合手順は Plugin Skills に記述します。
4. 宣言、ソース／公開エクスポート、依存関係、公開ファイル、テスト、README、Plugin Skills の整合性を保ちます。未使用のひな形や草案は削除します。Markdown の説明文の段落は、手動で改行せず、物理的な1行に記述します。
5. 統合が依頼に含まれる場合は、選択した App への登録をプレビューして適用し、該当する Skills を同期して、結果の動作を検証します。この Skill が適用されるという理由だけで、作成、登録、移行、その他の状態を変更するコマンドを実行しないでください。
6. testing and delivery に従います。変更したプラグインのチェックと、関連する利用側のチェックを実行し、依頼された実行時のワークフローを検証します。plugin inspect は任意の読み取り専用の登録診断であり、テストでも完了条件でもありません。結果、実施を省略したチェック、残る制限を正確に報告します。