プラグインを管理する

既定のテンプレートには、すでにいくつかのプラグインが含まれています。アプリ開発では通常、それらの認証、ユーザー、認可、ファイルの機能をそのまま使います。必要な機能が足りないことを確認してから、プラグインを追加してください。アプリ固有のタスクやプロジェクトは、先にプラグインにせず、アプリのコードに置きます。

このガイドでは、アプリでのプラグインの管理を扱います。プラグインの開発や、製品の完全な一覧は扱いません。コマンドは、サンプルアプリにインストールされた CLI で確認しています。使っているバージョンのオプションは --help で確認してください。

独自のプラグインを開発するには、まず プラグインを書くべきとき を読み、プラグインを作成する で現在のアプリにひな形を生成します。全体の流れは 最初のプラグインを書く を参照してください。

チームが公開したプラグインの場合は、インストールと登録の前に、プライベートレジストリと読み取りアクセスを設定します。ビルドと公開 を参照してください。

エージェントを使う場合

このアプリで使えるプラグインの機能を確認し、既存の業務機能のうちどれがそれを使っているかを特定してください。

まず、インストール済みの依存関係、実際の登録、関連するガイダンスを読んでください。名前から機能を推測したり、すでにあるものを作り直したりしないでください。
この確認では、プラグインの追加、アップグレード、削除は行わないでください。

各機能がどのプラグインに依存しているか、どの公開の入口を使っているか、足りない管理ページや必要な設定があるかを説明してください。
依存関係の変更が必要な場合は、理由、互換性のあるバージョン、影響を受ける機能を説明してから、レビューできる変更案を用意してください。
ユーザーの権限と業務データは保持してください。

実際に変更する場合は、たとえば「スケジュールプラグインを互換性が確認されたバージョンに更新し、既存の定義と実行を検証する」のように、目的を明確にします。登録、更新、削除は、棚卸しの途中でついでに行うのではなく、タスクに合わせて行うべきです。

エージェントを使わない場合

インストールと登録を確認する

package.json の @nocobase/app-plugin-* の依存関係と、ロックファイルで解決されたバージョンを確認します。続いて、3 つの構成ルートを確認します。

インストールされたパッケージが登録されているとは限りません。3 つのリストが一致している必要はありません。コマンドだけのプラグインには CLI の入口が必要です。配列の順序は提供内容の順序に影響するため、アルファベット順に見せるためだけに並べ替えないでください。

.agents/skills/ 以下のスキルも、プラグインが有効であることの証明にはなりません。直接の依存関係がスキルを提供することがあるためです。構成ルートが正です。アプリのプラグインパッケージは、デプロイに含まれるよう通常 dependencies に入れます。クライアントプラグインが自動的に開発専用の依存関係になるわけではありません。

既存の機能を使う

公開のサービストークン、クライアントのフック、コンポーネント、ルート、管理機能については、インストール済みのプラグインのスキルを読みます。プラグインの内部のテーブルに書き込んだり、内部のソースパスからインポートしたりせず、公開のエクスポートを使います。

たとえばプロジェクトの機能は、閲覧、作成、割り当てを認可プラグインで宣言し、ユーザーとロールの管理を再利用します。別の権限パッケージやロールの保存先は必要ありません。それでも、アプリは機能を実際のページと API に接続する必要があります。インストールしただけでは、業務機能は実装されません。

足りないプラグインを登録する

以下のコマンドでは Scheduler を例にします。すでに登録されている場合は登録を省略します。別のプラグインに置き換える前に、その提供状況、バージョン要件、設定を確認してください。

pnpm nocobase plugin register @nocobase/app-plugin-scheduler --dry-run
pnpm nocobase plugin register @nocobase/app-plugin-scheduler

このコマンドは、依存関係をインストールし、エクスポートされた提供内容を接続し、スキルを同期します。package.json、ロックファイル、実際の Client、Server、CLI の登録を確認してください。互換性が確認されたバージョンには --version を使います。新しいパッケージの既定のバージョンが、すべてのアプリと自動的に互換性があるわけではありません。

pnpm add はパッケージをインストールしますが、実行時の登録の代わりにはなりません。--no-install には、解決可能なインストール済みの依存関係が必要です。--disabled は実行時の提供内容を有効にせずにインストールし、機能は使えるようになりません。出力で、実際に処理されたルートを確認してください。

プラグインを更新する

1 つのプラグインの更新をプレビューして適用します。

pnpm nocobase plugin update @nocobase/app-plugin-scheduler --dry-run
pnpm nocobase plugin update @nocobase/app-plugin-scheduler

名前は位置引数で、--plugin ではありません。省略すると登録済みのすべてのプラグインが更新されるため、1 つの機能を変更するときはパッケージ名を指定してください。

pnpm は宣言されたバージョン範囲に従います。範囲を固定していると、新しいバージョンが入らないことがあります。範囲外への変更では、互換性のある対象を確定し、宣言とロックファイルを更新し、スキルを同期して、結果を確認します。プラグインの更新はテンプレートの変更をマージせず、NocoBase Core をアップグレードする の代わりにもなりません。

マイグレーション、設定、公開 API の変更を確認し、影響を受ける機能を検証してビルドし直します。開発用の依存関係を更新しても、すでにデプロイされた成果物は変わりません。

機能の無効化とプラグインの削除を区別する

画面から一時的に外す場合は、入口を隠すことが求められているのか、使えなくすることが求められているのかを判断します。メニューを隠しても、URL への直接アクセスや API リクエストは止まりません。無効化の動作は実際の入口で強制し、元に戻すために必要なコードとデータは残します。

アンインストールの前に、インポート、Client/Server/CLI の登録、ルート、設定、サービス、テスト、依存している機能を検索します。パッケージを削除する前に、それらの参照を移行または削除します。

以下の <name> は、使われていないことが確認されたプラグインのプレースホルダーです。まだ業務機能を支えているプラグインには実行しないでください。

pnpm nocobase plugin unregister '@nocobase/app-plugin-<name>' --dry-run
pnpm nocobase plugin unregister '@nocobase/app-plugin-<name>'

pnpm nocobase package remove <full-package-name> も NocoBase の直接の依存関係を削除し、プラグインパッケージについては登録解除に処理を委ねます。マニフェストの行だけを削除すると、登録や同期されたファイルが残ることがあります。

登録解除は、過去の業務データをどう扱うかを決めるものではなく、データベースのロールバック計画でもありません。プラグインのディレクトリやテーブルをついでの片付けとして削除するのではなく、保持、移行、削除を別に設計してください。

プラグインの画面を拡張する

ページのオーバーライドは、ルートの識別子、パス、アクセス条件を保ったまま、取り決めに従って遅延読み込みのコンポーネントを置き換えます。同じパスを宣言し直したり、1 つのルートに複数のオーバーライドを組み合わせたりしないでください。現在のサインインページと登録ページは、認証プラグインを使っていてもアプリが所有しています。

node_modules/ や .agents/skills/ のパッケージの内容を編集しないでください。アプリのルールは .agents/rules/ に置き、共有プラグインの不具合はそのソースリポジトリで修正します。

結果を確認する

依存関係、ロックファイル、3 つのルートすべて、同期されたスキル、実際の利用箇所を確認します。影響を受ける型チェック、テスト、ビルドを実行します。マイグレーション後は既存のデータを、エンドポイントの変更後は API ドキュメントを確認します。ブラウザーで、正常なアクセスと一般ユーザーの権限の境界を確認します。

手動の変更や中断でスキルが不整合になった場合は、同期し直します。

pnpm nocobase skills sync

同期で修復されるのはガイダンスのコピーであり、プラグインの登録やアプリのコードではありません。続けて アプリ開発の概要 と テスト を読んでください。