nocobase-create-app

NocoBase 3 アプリケーションの作成

この Skill では、新しいプロジェクトを作成、設定し、ローカルで実行できる状態にします。これは開発用のソースコードであり、デプロイするビルド済みアプリケーションではありません。アプリケーションの開発方法については説明しません。アプリケーションが作成された時点で、そのアプリケーション独自の AGENTS.md と .agents/skills/ が優先されます。これらはインストールされたバージョンに対応していますが、この Skill は対応していないため、内容が異なる場合はアプリケーション側のものを優先してください。

開始する前に

• 作業ディレクトリに NocoBase アプリケーションがすでに存在する場合（AGENTS.md と同じ場所に nocobase フィールドを含む package.json がある場合）、この Skill は使用しないでください。その AGENTS.md を読み、記載されている内容に従ってください。

• NocoBase 3 は pnpm create @nocobase/app@beta で作成します。パッケージが見つからない場合も含め、NocoBase 2 の手順や nb CLI に切り替えないでください。代わりに「トラブルシューティング」を参照してください。

• 依頼がこの Skill の対象か確認してください。プロジェクトとは、誰かが変更を加え、ローカルで開発するソースコードです。インストールとは、通常は本番環境で実行するだけのビルド済み NocoBase を指し、nocobase-app-installer の対象です。

  ユーザーの依頼内容	Skill
  NocoBase のインストール、作成、セットアップ、または開発目的で試すこと	これ
  アプリケーションを本番環境またはサーバーにデプロイすること	nocobase-app-installer、--archive

  デプロイの依頼は nocobase-app-installer に引き継ぎ、ここでの作業を終了してください。

• Windows では WSL を使用してください。以下のコマンドは Bash などの POSIX シェルを想定しています。サブシェルとインライン環境変数は PowerShell や cmd では動作しません。

• node --version（24 以降）と pnpm --version（11）を確認してください。どちらかが見つからない場合、またはバージョンが要件と一致しない場合は、作成を開始せず、ユーザーに次の内容を伝えてください。

  • 不足しているツール、または確認されたバージョンと、必要なバージョン。
  • 使用している場合は既存のバージョン管理ツール（nvm install 24 や fnm install 24 など）を優先した、その OS でのインストールコマンド。pnpm の場合は corepack enable && corepack prepare pnpm@11 --activate または npm install -g pnpm@11。
  • 新しいバージョンを PATH に反映するため、その後新しいシェルを開くこと。

  ユーザーから依頼されない限り、どちらも自分でインストールしないでください。続行する前に、両方のバージョンを再確認してください。

• アプリケーションは、ユーザーが指定したディレクトリ、または現在のディレクトリが空の場合はそこに作成してください。ディレクトリは新規または空である必要があり、その名前がアプリケーション名になります。名前は小文字または数字で始まり、小文字、数字、ドット、ハイフン、アンダースコアのみを含めてください。ディレクトリが空でない場合、または名前が無効な場合は、別のディレクトリをユーザーに指定してもらってください。ファイルを上書きしないでください。また、入れ子になったプロジェクトを作成して、後からファイルを移動することは絶対にしないでください。

作成

pnpm create @nocobase/app@beta では、名前として . を指定できません。親ディレクトリから対象ディレクトリの名前を指定して実行すると、ファイルが対象ディレクトリに直接生成されます。

(cd <parent-directory> && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 npm_config_registry="${NOCOBASE_REGISTRY:-https://registry.npmjs.org}" pnpm create @nocobase/app@beta <name> --template-tag=beta --json)

• @nocobase/create-app を含む NocoBase 3 のパッケージは、公開 npm レジストリに公開されています。このコマンドは、そのプロセスに限ってレジストリを設定します。また、NOCOBASE_REGISTRY を指定すると、プライベートレジストリや未リリースのローカルスナップショットを選択できます。create-app はテンプレートと依存関係のインストールに同じレジストリを使用し、公開レジストリ以外への変更がある場合に限り、プロジェクトの .npmrc に記録します。ユーザーの pnpm 設定は変更しないでください。
• 作成ツール（@nocobase/app@beta）とテンプレート（--template-tag=beta）の両方で beta チャンネルを使用してください。ツールだけを選択しても、テンプレートのチャンネルは選択されません。beta を解決できない場合は、latest にフォールバックしないでください。ユーザーが明示的に指定したバージョンまたはローカルスナップショットが優先されます。
• NOCOBASE_REGISTRY は、未リリースのスナップショットなど、シェルが別のレジストリを参照している場合にのみ設定します。create-app もこの値を読み取ります。
• PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 を設定すると、数分前に公開されたバージョンを pnpm でインストールできます。
• --json を指定すると、プロンプトは表示されません。標準出力には JSON ドキュメントが 1 つ出力され、進行状況は標準エラー出力に出力されるため、標準出力のみを解析してください。これは、すべての pnpm nocobase … --json コマンドが出力するエンベロープです。ok は作成が成功したかどうかを示し、result には生成された内容が含まれます。失敗した場合は、error.code、error.message、error.details に停止した箇所が示されます。create-app 0.1.0-beta.23 以前は、代わりにフラットな結果を出力します。この場合は、トップレベルの status が success または error を示し、stage、message、directory、nextCommands がトップレベルにあります。同じフィールドを参照してください。
• デフォルトのテンプレートはアプリケーション開発用で、--template フラグは不要です。--template-tag=beta はそのまま指定してください。最初にサンプル機能を通じて NocoBase を試したい場合は、--template=examples を追加してください。

ほかの作業を行う前に、結果を確認してください。

結果	対応
ok: true（フラットな結果では status: "success"）	以下の手順に進みます。warnings があれば報告してください。
INVALID_USAGE、stage が input（終了コード 2）	引数を修正してください。何も作成されていません。
TEMPLATE_DOWNLOAD_FAILED、stage が download	ネットワークと設定済みのレジストリを確認してください。何も作成されていません。
INSTALL_FAILED、stage が install	プロジェクトは存在します。プロジェクト内で pnpm install を実行して再試行し、その後 Configure に進んでください。再作成しないでください。
DRIVER_VERIFICATION_FAILED、stage が verify	再ビルド後も SQLite ドライバーのネイティブアドオンを読み込めませんでした。原因が記載されているメッセージを報告してください。
NODE_UNSUPPORTED	Node.js のバージョンが 24 より古いです。アップグレードをユーザーに依頼してください。何も実行されていません。
その他の失敗	メッセージとディレクトリをユーザーに報告してください。

stage は error.details.stage に、ディレクトリは error.details.directory にあります。フラットな結果では、それぞれ stage と directory にあります。

再試行のためにディレクトリを削除しないでください。

設定

ここからはアプリケーションのディレクトリで作業します。今すぐそのディレクトリの AGENTS.md を読んでください。このセッションの開始後に追加されたため、まだ読み込まれていない可能性があります。

result.nextCommands はアプリケーションを SQLite 用に設定してから起動します。インストールを再試行した結果、それらが見つからない場合は、pnpm nocobase config init、pnpm nocobase config check、続けて pnpm dev を実行します。ユーザーがすでにデータベースを指定している場合を除き、実行前にどのデータベースを使うか尋ね、以下の手順に従って調整してください。SQLite 以外のデータベースには、そのドライバー、--dialect、および config init と config check の間に実行する config set が必要です。すべての pnpm nocobase config コマンドに --json を付け、終了コードだけでなく、出力されたドキュメントに基づいて対応してください。ok は成功したかどうか、result は生成された内容を示し、失敗時の error.code、error.suggestions、error.details は次の対応を示します。

1. データベースを選択します。 ユーザーが指定したものを使うか、ユーザーに尋ねてください。SQLite はドライバーがテンプレートに含まれているため、インストールするものはありません。ほかのデータベースの場合は、先にドライバーをインストールしてください。例：pnpm add @nocobase/db-postgres@beta
2. pnpm nocobase config init --dialect <dialect> --json は、アプリケーションの config.example.yml から、生成されたシークレットを含む config.yml を作成します。
   • 何もインストールしません。ドライバーが見つからない場合は、何も書き込まずに error.code が DRIVER_MISSING のエラーで終了します。ドライバーを追加する pnpm add コマンドは error.suggestions[0].run にあります。そのコマンドを実行してから、config init を再度実行してください。
   • すでに設定済みのアプリケーションは status: "success-noop" として報告されるため、この一連の手順を再実行しても安全です。
   • result.requiredSettings には、まだプレースホルダーのままの接続設定が列挙されます。
3. pnpm nocobase config set key=value … --json は、各 requiredSettings を設定します。例：database.connections.main.host=db.internal。パスワードは必ず環境変数から設定します。詳しくは「シークレット」を参照してください。
4. pnpm nocobase config check --json は、アプリケーションを起動する前に成功する必要があります。このコマンドはアプリケーションを起動せずに設定を読み込み、データベースに接続します。失敗した場合は error.code が CONFIG_INVALID となり、問題の内容は error.details.findings に示されます。それぞれの項目にはキーと、該当する場合は実行すべき fix が記載されています。修正を適用して、もう一度実行してください。

特定のデータベースの詳細については、アプリケーション内の .agents/skills/nocobase-app-development/references/database-connections.md を読んでください。

pnpm nocobase config init --help でコマンドが存在しないと表示された場合、そのアプリケーションはこれらのコマンドが導入される前のバージョンです。このセクションではなく、そのアプリケーションの AGENTS.md に従ってください。

起動

nextCommands の最後にある pnpm dev は終了しません。バックグラウンドで実行し、出力される URL を待ってください。アプリケーションの準備が完了してから Local: の行が出力され、URL には /main/ などのアプリケーションのパスが含まれます。たとえば curl -I でその URL にリクエストを送り、成功応答を確認してから成功を報告してください。設定されていないアプリケーションの起動は拒否されます。pnpm nocobase config check --json を実行し、示された修正に従ってください。

シークレット

• 会話の中でパスワードを尋ねたり、コマンドラインに入力したりしないでください。ユーザーに環境変数へ設定するよう依頼し、その後 pnpm nocobase config set --from-env database.connections.main.password=<VARIABLE> --json を実行してください。
• config.yml や、それに含まれるシークレットを出力しないでください。
• 手順を成功させるために --force を指定したり、config.yml を削除したり、データベースを削除したりしないでください。config init --force は既存の設定を置き換えるため、ユーザーがそれを明示的に求めた場合に限り使用してください。

完了

ユーザーに次のことを伝えてください。

• アプリケーションのディレクトリと URL。
• 最初のサインインアカウント。設定の users.initialAdmin に基づきます。デフォルトでは、ユーザー名 nocobase（メールアドレス [email protected]）、パスワード admin123 です。デフォルトを決めつけずにこのキーを確認し、ユーザーが設定したパスワードを再掲しないでください。サインイン後にデフォルトのパスワードを変更するよう伝えてください。
• このセッションがサービスを起動しており、セッションの終了時に停止することと、再起動方法：アプリケーションのディレクトリで pnpm dev を実行します。ユーザー自身のターミナルか、次のセッションで実行できます。
• 続行方法。アプリケーションの AGENTS.md と Skills は、このセッションの開始後に表示されました。再起動せずに読み込むエージェントもあれば、セッション開始時にのみ読み込むエージェントもあります。決めつけず、どちらに当てはまるか確認してください。
  • ここで読み込まれている場合（たとえば、アプリケーションの nocobase-app-development Skill が利用可能な Skills に含まれ、アプリケーションのディレクトリがこのセッションの作業ディレクトリである場合）：このセッションで続行できると伝えてください。新しいセッションは不要です。
  • ここで読み込まれていない場合：アプリケーションのディレクトリで新しいエージェントセッションを開始するよう伝え、その方法を正確に説明してください。アプリケーションがこのセッションのディレクトリにある場合は、このセッションを終了して同じディレクトリで新しいセッションを開始するだけです。それ以外の場合は、フルパスと、たとえば Claude Code なら cd /work/my-app && claude のように、そこでエージェントを起動するコマンドを示してください。デスクトップクライアントでは、そのディレクトリをプロジェクトとして開き、新しいセッションを開始します。
• 実行中のアプリケーションのホームページには、エージェントを使った開発方法がすでに案内されています。別途、最初の機能を作るためのガイドへのリンクを追加せず、次の手順はそちらを案内してください。
• 後で本番環境に移行する場合：アプリケーション独自の nocobase-deployment Skill でデプロイ用アーカイブを作成し、グローバルの nocobase-app-installer Skill で実行するマシンにインストールします。この作業は今は開始しないでください。

この引き継ぎは簡潔にしてください。各項目は1行とし、コマンドとパスはコード形式で記述し、このユーザーに該当するケースのみ記載してください。

Skills が読み込まれていないものの、ユーザーがこのセッションで作業を続けたい場合は、それらに依存しないでください。アプリケーションの AGENTS.md に従い、関連する .agents/skills/<name>/SKILL.md を直接読んでください。

トラブルシューティング

症状	対処
作成時に @nocobase/create-app が見つからない（404）	パッケージ名とパブリック npm へのアクセスを確認してください。プライベートスナップショットの場合は、NOCOBASE_REGISTRY にそのパッケージを含むレジストリを設定してから、Create コマンドを再実行してください。
作成時に Unknown option: 'registry' と表示される	pnpm create は --registry を受け付けません。レジストリを npm_config_registry に設定し、記載どおりに Create コマンドを実行してください。
アプリケーション内で @nocobase/... が見つからない（404）	パッケージ名とバージョンを確認してください。プライベートレジストリの場合は、プロジェクトの .npmrc に一致する @nocobase:registry のエントリがあることを確認してください。
一致するバージョンがない、または最新バージョンが無視される	コマンドに PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 を設定してください。
Could not locate the bindings file	このプラットフォームに一致するビルド済み better-sqlite3 バイナリがありません。C++ ツールチェーンをインストールし、pnpm-workspace.yaml の allowBuilds に better-sqlite3: true を設定してから、rm -rf node_modules && pnpm install を実行してください。
Skills を同期できなかったという警告が表示される	アプリケーションで pnpm nocobase skills sync を実行してください。
pnpm dev または pnpm start で設定されていないと表示される	pnpm nocobase config init --json を実行し、続いて pnpm nocobase config check --json を実行して、結果に従ってください。

アプリケーションの手順については、https://github.com/nocobase/nocobase/blob/v3-develop/docs/docs/en/capabilities/quick-start.md を参照してください。