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

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 でインストールされたもの、またはフレームワークに組み込まれたもの)。

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

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

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

yarn pm create @my-project/plugin-hello

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

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

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

関連リンク