#プロジェクトのディレクトリ構造

Gitからソースコードをクローンする場合でも、create-nocobase-app を使ってプロジェクトを初期化する場合でも、生成されるNocoBaseプロジェクトは、基本的には Yarn Workspace をベースとしたモノレポです。

#トップレベルディレクトリの概要

以下の例では、my-nocobase-app/ をプロジェクトディレクトリとしています。環境によっては多少異なる場合があります。

my-nocobase-app/
├── packages/              # プロジェクトのソースコード
│   ├── plugins/           # 開発中のプラグインソースコード（未コンパイル）
├── storage/               # ランタイムデータと動的に生成されるコンテンツ
│   ├── apps/
│   ├── db/
│   ├── logs/
│   ├── uploads/
│   ├── plugins/           # コンパイル済みプラグイン（UIからアップロードされたものも含む）
│   └── tar/               # プラグインのパッケージファイル（.tar）
├── scripts/               # ユーティリティスクリプトとツールコマンド
├── .env*                  # 各環境の変数設定
├── lerna.json             # Lernaワークスペース設定
├── package.json           # ルートパッケージ設定、ワークスペースとスクリプトを宣言
├── tsconfig*.json         # TypeScript設定（フロントエンド、バックエンド、パスエイリアス）
├── vitest.config.mts      # Vitestユニットテスト設定
└── playwright.config.ts   # Playwright E2Eテスト設定

#packages/ サブディレクトリの説明

packages/ ディレクトリには、NocoBaseのコアモジュールと拡張可能なパッケージが含まれています。内容はプロジェクトのソースによって異なります。

• create-nocobase-app で作成されたプロジェクト：デフォルトでは packages/plugins/ のみが含まれており、カスタムプラグインのソースコードを格納するために使用されます。各サブディレクトリは独立したnpmパッケージです。
• 公式ソースリポジトリをクローンした場合：core/、plugins/、pro-plugins/、presets/ など、より多くのサブディレクトリが表示されます。これらはそれぞれフレームワークのコア、組み込みプラグイン、公式のプリセットソリューションに対応しています。

どちらの場合でも、packages/plugins はカスタムプラグインの開発とデバッグを行う主要な場所となります。

#storage/ ランタイムディレクトリ

storage/ には、ランタイムで生成されるデータとビルド出力が格納されます。一般的なサブディレクトリの説明は以下の通りです。

• apps/：マルチアプリケーション環境での設定とキャッシュ。
• logs/：ランタイムログとデバッグ出力。
• uploads/：ユーザーがアップロードしたファイルとメディアリソース。
• plugins/：UIからアップロードされた、またはCLIでインポートされたパッケージ済みプラグイン。
• tar/：yarn build <plugin> --tar 実行後に生成されるプラグインの圧縮パッケージ。

通常、storage ディレクトリは .gitignore に追加し、デプロイやバックアップ時には個別に処理することをお勧めします。

#環境設定とプロジェクトスクリプト

• .env、.env.test、.env.e2e：それぞれローカル実行、ユニット/統合テスト、エンドツーエンドテストに使用されます。
• scripts/：一般的な運用スクリプト（データベースの初期化、リリース補助ツールなど）が格納されます。

#プラグインのロードパスと優先順位

プラグインは複数の場所に存在する可能性があります。NocoBaseは起動時に以下の優先順位でロードします。

1. packages/plugins 内のソースコードバージョン（ローカル開発とデバッグ用）。
2. storage/plugins 内のパッケージバージョン（UIからアップロードされたもの、またはCLIでインポートされたもの）。
3. node_modules 内の依存パッケージ（npm/yarnでインストールされたもの、またはフレームワークに組み込まれたもの）。

同じ名前のプラグインがソースディレクトリとパッケージディレクトリの両方に存在する場合、システムはローカルでの上書きとデバッグを容易にするため、ソースコードバージョンを優先してロードします。

#プラグインディレクトリのテンプレート

CLIを使ってプラグインを作成します。

yarn pm create @my-project/plugin-hello

生成されるディレクトリ構造は以下の通りです。

packages/plugins/@my-project/plugin-hello/
├── dist/                    # ビルド出力（必要に応じて生成）
├── src/                     # ソースコードディレクトリ
│   ├── client/              # フロントエンドコード（ブロック、ページ、モデルなど）
│   │   ├── plugin.ts        # クライアントサイドプラグインのメインクラス
│   │   └── index.ts         # クライアントサイドのエントリ
│   ├── locale/              # 多言語リソース（フロントエンドとバックエンドで共有）
│   ├── swagger/             # OpenAPI/Swagger ドキュメント
│   └── server/              # サーバーサイドコード
│       ├── collections/     # コレクション定義
│       ├── commands/        # カスタムコマンド
│       ├── migrations/      # データベースマイグレーションスクリプト
│       ├── plugin.ts        # サーバーサイドプラグインのメインクラス
│       └── index.ts         # サーバーサイドのエントリ
├── index.ts                 # フロントエンドとバックエンドのブリッジエクスポート
├── client.d.ts              # フロントエンドの型定義
├── client.js                # フロントエンドのビルド成果物
├── server.d.ts              # サーバーサイドの型定義
├── server.js                # サーバーサイドのビルド成果物
├── .npmignore               # 公開時の無視設定
└── package.json

ビルドが完了すると、dist/ ディレクトリと client.js、server.js ファイルはプラグインが有効になったときにロードされます。 開発段階では src/ ディレクトリのみを修正すればよく、公開前には yarn build <plugin> または yarn build <plugin> --tar を実行するだけで済みます。