機能はアプリに置くべきか、プラグインにすべきか
現在の業務に固有のコードは、アプリの client/、server/、database/、cli/ のディレクトリに直接置けます。独立した保守、明確な拡張の入口、複数のアプリへの組み込みが必要な場合は、packages/app-plugin-<name>/ を検討します。ローカルのプラグインはアプリと一緒にビルドされ、npm での公開は必要ありません。プラグインを書くべきとき を参照してください。
インストールしたプラグインにページがない、または機能が動かないのはなぜか
依存関係がインストールされていること、実行時の入口が登録されていること、ページが組み込まれていることは、それぞれ別の状態です。プラグインがどの Client、Server、CLI の入口を提供しているかと、アプリの対応する plugins.ts での登録を確認してください。サービスやスキルだけを提供し、ページはアプリが組み立てることを想定しているプラグインもあります。データベースのリソースにはマイグレーションも必要です。プラグインを使う と プラグイン一覧 を参照してください。
アプリとプラグインのコンポーネントは決まった構成に従う必要があるか
コンポーネントは、shadcn のプリミティブを使って自由に書き、整理できます。モジュール化されたコンポーネントは、まず NocoBase UI Library を確認してください。プラグインは、業務のニーズに応じて、実行時のコンポーネントを提供することも、サービス、取り決め、例だけを提供することもできます。コンポーネントとスタイル を参照してください。
コンポーネントを再利用するには UI Registry を公開する必要があるか
いいえ。コンポーネントやブロックを、エージェントが必要に応じて取得、変更、組み合わせできるソースのアセットにしたい場合に公開します。通常のソースの整理、共有のパッケージの依存関係、実行時のプラグインでも、コードを再利用できます。
配布するソースのアセットは、実行時のプラグインと並べて、packages/announcements-ui/ などの別のパッケージで管理します。アセットは、公開側の非公開のプラグインのファイルや、公開側だけのエイリアスをインポートしてはいけません。一緒に配布するファイルは、インストール先がそれを保つ場合は、相対インポートを使えます。UI のソースアセットを公開する を参照してください。
ローカルの UI のアセットに Registry のサーバーは必要か
いいえ。アイテムの JSON をビルドし、そのローカルのパスを shadcn add に渡します。pnpm --filter をサブパッケージで実行する場合は、絶対パスのほうがわかりやすくなります。静的なホスティングが必要なのは、マシンをまたいで URL で配布する場合だけで、既存のサイトを再利用できます。ソースのアセットをローカルでインストールする を参照してください。
ServiceProvider はサーバーだけのものか
クライアントとサーバーの両方のランタイムが、サービスの登録とライフサイクルのフックに ServiceProvider を使い、それぞれ別のコンテナとインスタンスを持ちます。React の Provider は React のコンポーネントツリーでコンテキストを提供するもので、サービスコンテナとは異なります。ServiceProvider と API リファレンス を参照してください。
config.yml を変更しても効果がないのはなぜか
環境変数による上書きと、APP_CONFIG_FILE が別のファイルを選んでいないかを確認してください。YAML の ${NAME} は環境変数の値を展開しません。ブラウザーで保存された設定が、新しいテーマの既定値を上書きすることがあります。一部のサービスは起動時に設定を読み込むため、再起動か明示的な再読み込みの処理が必要です。設定リファレンス を参照してください。
初期管理者のパスワードを変えてもアカウントが更新されないのはなぜか
users.initialAdmin は空のユーザーのデータベースを初期化するもので、既存のユーザーのパスワードを再設定する入口ではありません。データベースをリセットするのではなく、アプリのアカウント管理か再設定の手順を使ってください。
コマンドがほかのチュートリアルと異なるのはなぜか
チュートリアルが NocoBase 3 を対象にしていること、作業ディレクトリが意図したアプリであること、CLI がそのアプリのものであることを確認してください。ソースでは pnpm nocobase を、デプロイの出力では node dist/cli/index.js を使います。commands --json と各コマンドの --help を確認してください。本番のビルドには、開発用やプラグインの登録用のコマンドがすべて残るわけではありません。コマンドラインリファレンス を参照してください。
アプリには既定でどのプラグインが含まれるか
テンプレートの依存関係が含まれるパッケージを示し、登録のファイルが組み込まれた実行時の入口を決めます。どちらもバージョンによって変わることがあります。アプリの package.json、そのロックファイル、Client/Server/CLI の登録を確認してから、プラグイン一覧 の基準を参照してください。node_modules/ にパッケージがあるだけでは、有効になっていることの証明にはなりません。
テーブルを作成すると、自動で API が公開されるか
コレクションを作成しても、クライアントに自動で公開されることはありません。アプリやプラグインが、エンドポイントを宣言し、入力を検証し、身元を確定し、権限を適用する必要があります。リモートの Repository のクライアントにも、対応するサーバーのエンドポイントが必要です。HTTP ルートと API を参照してください。
マイグレーションでチェックサムの不一致が報告されるのはなぜか
適用済みのマイグレーションが、現在のソースと異なっています。過去のマイグレーションの編集、間違ったブランチ、一致しないデプロイがないかを確認してください。通常、新しい変更にはマイグレーションを追加します。db repair は、編集がデプロイ済みのスキーマの意味を変えていないことを確認してから検討してください。チェックを黙らせるためだけに、データベースをリセットしないでください。データベースのマイグレーション を参照してください。
ダイアレクトを変えると既存のデータは移るか
いいえ。変わるのは接続で、データの置き場所ではありません。対象のデータベースで、フィールドの型、インデックス、制約、照会、トランザクション、プラグインの動作を検証してから、データの移行と検証を手配してください。テスト済みのデータベースのイメージは、すべてのサーバーのバージョンを保証するものではありません。データベースの対応状況とバージョンの互換性 を参照してください。
すべての @nocobase のパッケージを同じバージョンにすべきか
いいえ。ランタイム、ライブラリー、プラグイン、ひな形のツールは、それぞれ独立してバージョンが付けられています。テンプレートの依存関係と peer の範囲に従い、ロックファイルを保ってください。アップグレードでは、テンプレートの変更、マイグレーション、ローカルのプラグインの確認も必要です。NocoBase Core をアップグレードする を参照してください。
どのディレクトリは再生成できるか
node_modules/ と dist/ は、ソースとロックファイルからビルドし直せます。同期されたスキルにも管理されたソースがあります。実行時に生成される storage/ には、SQLite のデータベース、アップロードされたファイル、ログが含まれることがあるため、捨ててよいビルドのキャッシュとして扱わないでください。永続化とバックアップは、実際のストレージの設定に合わせて計画してください。ディレクトリとファイルの規約 を参照してください。
開発中のプレビューと本番のデプロイはどう違うか
ローカルでは開発用のコマンドを使います。Studio のプレビューについては Studio のドキュメントを参照してください。独立した本番のアプリは、ビルドの出力を使い、実行時のデータを保ったまま、Docker か PM2 と app-installer でデプロイします。デプロイ方法を選ぶ を参照してください。
問題の報告には何を含めるべきか
最小限の再現手順、実際の結果と期待される結果、オペレーティングシステムとアーキテクチャ、Node と pnpm のバージョン、関連するパッケージのバージョンを伝えてください。ソースでの開発中、ビルド中、デプロイ中のどれで起きるかを明記してください。データベースの問題では、ダイアレクトとサーバーのバージョンも含めます。パスワード、キー、セッション、設定ファイル全体ではなく、伏せ字にしたエラーとコマンドを共有してください。