プロジェクト構成

ディレクトリの概要

アプリを作成する と、直接編集できるソースコードが手に入ります。以下は、既定のアプリテンプレートでよく使う開発の場所です。設定、インストールされた依存関係、ビルドの出力は、それぞれのセットアップ手順のあとに現れます。

my-app/
├── client/              # ページ、コンポーネント、クライアントのロジック
├── server/              # API と業務のサービス
├── database/            # 接続ごとにまとめたマイグレーションとシード
├── cli/                 # アプリのコマンドと CLI のプラグイン
├── tests/               # テストとテストのヘルパー
├── public/              # 静的アセット
├── packages/            # ローカルの workspace のパッケージ（任意）
├── .agents/
│   ├── rules/           # プロジェクトが所有するエージェントのルール
│   └── skills/          # 依存関係から同期したスキル（生成）
├── AGENTS.md            # エージェント向けガイダンスの入口
├── config.example.yml   # 設定の例
├── config.yml           # ローカルの設定（セットアップ時に生成）
├── package.json         # スクリプトと依存関係
├── pnpm-lock.yaml       # 解決済みの依存関係のバージョン
├── pnpm-workspace.yaml  # workspace の設定
├── node_modules/        # インストール済みの依存関係（生成）
├── dist/                # ビルドの出力（生成）
└── storage/             # 実行時のデータ

ディレクトリはテンプレートのバージョンやアプリの機能によって異なります。packages/ などの任意のディレクトリは、ツリーに合わせて空のディレクトリを追加するのではなく、必要になったときに作成してください。

ページ、API、データの置き場所

ページと API は登録の入口に接続します。ファイルを追加するだけではアクセスできるようになりません。client/extensions/ にインストールした UI のソースもアプリのものであり、インポートでページやコンポーネントに接続します。

database/ はリソースを接続名ごとにまとめます。main が既定の接続です。実行済みのマイグレーションは残し、以降のスキーマの変更には新しいマイグレーションを追加します。実装の詳細は テーブルと初期データ を参照してください。

たとえば顧客管理では、通常、テーブルのマイグレーション、API のルート、ページ、対応する登録ファイルがかかわります。最初の機能を開発する に沿って進めると、これらの場所が動く機能の中でどう組み合わさるかがわかります。

設定、依存関係、プラグイン

設定ファイル

現在の環境の接続情報を変えるには config.yml を使います。業務ロジック用の設定項目を追加するときは、server/config/ の定義を更新します。読み込みの動作とコマンドについては、アプリの設定 を参照してください。

依存関係とプラグインの登録

package.json には、依存関係の宣言とともに、開発、テスト、ビルドのスクリプトが含まれます。pnpm-lock.yaml は解決された依存関係のバージョンを記録し、ソース管理に含めます。

テンプレートは、ユーザー、認証、認可、ファイルなどの機能をプラグインで提供します。package.json はどのパッケージがインストールされているかを、登録ファイルはどの提供内容が接続されているかを示します。

プラグインが 3 つの入口すべてを提供するとは限らず、開発用のスキルだけを提供するパッケージもあります。依存関係のインストール、プラグインの登録、ページへの組み込みは、それぞれ別のステップです。手順は プラグインを管理する を、個々の機能は プラグイン一覧 を参照してください。

ローカルのプラグインや共有パッケージは packages/ に置き、ワークスペースのパッケージのディレクトリは pnpm-workspace.yaml で設定します。UI のソースアセットを独立して配布する場合は、そこで UI Registry のパッケージを管理することもできます。詳しい構成は プロジェクトのディレクトリとファイルの規約 を参照してください。

テストの置き場所

テストは tests/ に置き、検証するコードごとに整理します。

Vitest のテストは、アプリのルートで pnpm test を実行します。ブラウザーのテストは pnpm test:e2e を使い、テストの設定で指定された、動作中のアプリとサインイン情報が必要です。セットアップの手順は テスト を参照してください。

既存のプロジェクトでは別のディレクトリを使っていることがあります。その場合は、プロジェクトの vitest.config.ts と playwright.config.ts に従ってください。レポートで実際のテスト数を確認します。テストが 1 件もないまま正常終了しても、機能が検証されたことにはなりません。

エージェントが読むガイダンス

AGENTS.md は、アプリ開発のガイダンスの入口です。プロジェクトが所有する規約と、依存関係が提供するスキルを区別します。

業務の規約は、アプリの開発を続ける の説明に従ってプロジェクトのガイダンスに追加します。依存関係からスキルを更新するには、アプリのディレクトリで pnpm nocobase skills sync を実行します。その他のオプションは CLI リファレンス を参照してください。

生成されるファイルと実行時のデータ

次のものは、業務のソースコードとしては管理しません。

SQLite がデータベースを保存する場所は接続の設定で決まり、アプリのルートにあることもあります。storage/ 内のデータベースファイルや業務データを、ビルドのキャッシュのように削除しないでください。パスの完全なリファレンスは プロジェクトのディレクトリとファイルの規約 を参照してください。