Nocobase Create App Skill for Claude

Create a NocoBase 3 application

This Skill gets a new project created, configured and running locally: source code to develop, not a built application to deploy. It does not describe how to develop one: the moment the application exists, its own AGENTS.md and .agents/skills/ take over. Those match the version that was installed and this Skill does not, so prefer them wherever the two differ.

Before you start

• If the working directory already holds a NocoBase application — a package.json with a nocobase field, next to an AGENTS.md — do not use this Skill. Read that AGENTS.md and continue from it.
• NocoBase 3 is created with pnpm create @nocobase/app@beta. Never fall back to NocoBase 2 instructions or the nb CLI, including when a package cannot be found; see Troubleshooting instead.
• Check the request is this Skill's. A project is source code someone changes, developed locally; an installation is a built NocoBase that only runs, usually in production, and belongs to nocobase-app-installer:

| The user asks to | Skill |

| ------------------------------------------------- | ----------------------------------------------------------------------- |

| Install, create, set up or try NocoBase, to develop with | This one |

| Deploy an application to production or a server | nocobase-app-installer, --archive |

Hand a request to deploy over to nocobase-app-installer, and stop here.

• On Windows, work in WSL. The commands below assume a POSIX shell such as Bash; the subshell and the inline environment variable do not work in PowerShell or cmd.
• Check node --version (24 or later) and pnpm --version (11). If either is missing or does not match, stop before creating anything and tell the user:
• which tool is missing or which version was found, and which version is required;
• the command to install it on their operating system, preferring a version manager they already use, such as nvm install 24 or fnm install 24, and for pnpm corepack enable && corepack prepare pnpm@11 --activate or npm install -g pnpm@11;
• to open a new shell afterwards, so the new version is on PATH.

Do not install either yourself unless the user asks. Check both versions again before continuing.

• Create the application in the directory the user names, or in the current directory when it is empty. The directory must be new or empty, and its name becomes the application name: it starts with a lowercase letter or digit and contains only lowercase letters, digits, dots, dashes and underscores. If the directory is not empty or its name is invalid, ask the user for another one. Never overwrite files, and never create a nested project and move its files afterwards.

Create

pnpm create @nocobase/app@beta does not accept . as the name. Run it from the parent directory with the target directory's name, which generates the files directly into it:

(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 3 packages, @nocobase/create-app included, are published to the public npm registry. The command sets that registry only for this process while allowing NOCOBASE_REGISTRY to select a private registry or an unreleased local snapshot; create-app uses the same registry for the template and dependency installation, and records only a non-public override in the project's .npmrc. Leave the user's pnpm configuration unchanged.
• Use the beta channel for both the creation tool (@nocobase/app@beta) and the template (--template-tag=beta); selecting only the tool does not select the template channel. Do not fall back to latest if beta cannot be resolved. An explicit version or local snapshot requested by the user takes precedence.
• NOCOBASE_REGISTRY is set only when the shell is pointed at another registry, such as an unreleased snapshot; create-app reads it too.
• PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 lets pnpm install versions published minutes ago.
• --json never prompts. It prints one JSON document on stdout and progress on stderr, so parse stdout only. It is the envelope every pnpm nocobase … --json command prints: ok says whether creation worked, result holds what it produced, and a failure's error.code, error.message and error.details say where it stopped. create-app 0.1.0-beta.23 and earlier print a flat result instead, with status success or error and stage, message, directory and nextCommands at the top level; read the same fields there.
• The default template is the one to develop an application from and needs no --template flag; keep --template-tag=beta. Add --template=examples when the user wants to explore NocoBase through its example features first.

Read the result before doing anything else:

| Result | What to do |

| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |

| ok: true (status: "success" in a flat result) | Continue below. Report any warnings. |

| INVALID_USAGE, stage input (exit 2) | Fix the arguments. Nothing was created. |

| TEMPLATE_DOWNLOAD_FAILED, stage download | Check the network and the configured registry. Nothing was created. |

| INSTALL_FAILED, stage install | The project exists. Run pnpm install inside it to retry, then continue with Configure. Do not create it again. |

| DRIVER_VERIFICATION_FAILED, stage verify | The SQLite driver's native addon did not load, even after a rebuild. Report the message; it names the cause. |

| NODE_UNSUPPORTED | Node.js is older than 24. Ask the user to upgrade it; nothing ran. |

| any other failure | Report the message and the directory to the user. |

The stage is error.details.stage and the directory error.details.directory, or stage and directory in a flat result.

Never delete the directory to retry.

Configure

Work from the application directory from here on. Read its AGENTS.md now: it appeared after this session started, so it may not be loaded.

result.nextCommands configure the application for SQLite and then start it. When a retried install left you without them, they are pnpm nocobase config init, pnpm nocobase config check, then pnpm dev. Unless the user has already named a database, ask which one they want before running them, and adapt them as the steps below describe: a database other than SQLite needs its driver, a --dialect, and a config set between config init and config check. Pass --json to every pnpm nocobase config command and act on the document it prints, not on the exit code alone: ok says whether it worked, result holds what it produced, and a failure's error.code, error.suggestions and error.details say what to do next.

• Choose the database. Use the one the user named, or ask. SQLite needs nothing installed: the template depends on its driver. For any other database, install its driver first, for example pnpm add @nocobase/db-postgres@beta.
• pnpm nocobase config init --dialect <dialect> --json writes config.yml from the application's config.example.yml, with generated secrets.
• It installs nothing. When the driver is missing it writes nothing and fails with error.code DRIVER_MISSING; error.suggestions[0].run is the pnpm add that supplies it. Run that, then run config init again.
• An application that is already configured is reported with status: "success-noop", so re-running the sequence is safe.
• result.requiredSettings lists the connection settings still at a placeholder.
• pnpm nocobase config set key=value … --json sets each of the requiredSettings, for example database.connections.main.host=db.internal. A password is always set from an environment variable; see Secrets below.
• pnpm nocobase config check --json must pass before the application is started. It loads the configuration without starting the application and connects to the database. A failure has error.code CONFIG_INVALID and its findings in error.details.findings; each names its key and, where there is one, a fix to run. Apply the fixes and run it again.

For the details of a particular database, read .agents/skills/nocobase-app-development/references/database-connections.md in the application.

If pnpm nocobase config init --help reports that the command does not exist, the application predates these commands: follow its AGENTS.md instead of this section.

Start

The last of the nextCommands, pnpm dev, does not exit. Run it in the background and wait for the URL it prints: it prints a Local: line only once the application is ready, and the URL includes the application's path, such as /main/. Request that exact URL, for example with curl -I, expecting a successful response before reporting success. It refuses to start an application that is not configured; run pnpm nocobase config check --json and follow its fixes.

Secrets

• Never ask for a password in the conversation, and never put one on a command line. Ask the user to set it in an environment variable, then run pnpm nocobase config set --from-env database.connections.main.password=<VARIABLE> --json.
• Never print config.yml or any secret it contains.
• Do not pass --force, delete config.yml or drop a database to make a step pass. config init --force replaces an existing configuration and is only for when the user asks for exactly that.

Finish

Tell the user:

• The application directory and the URL.
• The first sign-in account. It comes from users.initialAdmin in the configuration: by default the username nocobase (email [email protected]) with the password admin123. Read that key rather than assuming the defaults, never repeat a password the user chose, and remind them to change the default one after signing in.
• That the service was started by this session and stops when the session ends, and how to start it again: pnpm dev in the application directory, run in their own terminal or by the next session.
• Where to continue. The application's AGENTS.md and Skills appeared after this session started. Some agents pick them up without a restart; others load them only when a session starts. Check which case applies instead of assuming:
• They are loaded here (for example, the application's nocobase-app-development Skill is among your available Skills, and the application directory is this session's working directory): tell the user they can continue in this session. No new session is needed.
• They are not loaded here: tell the user to start a new agent session in the application directory, and say exactly how. When the application is in this session's directory, they only need to end this session and start a new one in the same directory. Otherwise, give the full path and the command that starts your own agent there, for example cd /work/my-app && claude for Claude Code. In a desktop client, they open that directory as the project and start a new session there.
• The running application's homepage already includes guidance for developing with an Agent. Point the user there for next steps instead of adding a separate first-feature guide link.
• Going to production later: the application's own nocobase-deployment Skill builds its deployment archive, and the global nocobase-app-installer Skill installs it on the machine that runs it. One line; do not start it now.

Keep this handover short: one line per point, commands and paths in code formatting, and only the case that applies to this user.

If the Skills are not loaded but the user wants to keep working in this session anyway, do not rely on them: follow the application's AGENTS.md and read the relevant .agents/skills/<name>/SKILL.md directly.

Troubleshooting

| Symptom | Fix |

| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |

| @nocobase/create-app not found (404) when creating | Check the package name and public npm access. For a private snapshot, set NOCOBASE_REGISTRY to the registry that contains it and rerun the Create command. |

| Unknown option: 'registry' when creating | pnpm create takes no --registry. Run the Create command as written, with the registry in npm_config_registry. |

| @nocobase/... not found (404) in the application | Check the package name and version. For a private registry, confirm the project's .npmrc has the matching @nocobase:registry entry. |

| No version matches, or the newest one is ignored | Set PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 for the command. |

| Could not locate the bindings file | No prebuilt better-sqlite3 binary matches this platform. Install a C++ toolchain, set better-sqlite3: true under allowBuilds in pnpm-workspace.yaml, then run rm -rf node_modules && pnpm install. |

| A warning that the Skills could not be synchronized | Run pnpm nocobase skills sync in the application. |

| pnpm dev or pnpm start says it is not configured | Run pnpm nocobase config init --json, then pnpm nocobase config check --json, and follow the result. |

For an application walkthrough, see https://github.com/nocobase/nocobase/blob/v3-develop/docs/docs/en/capabilities/quick-start.md.