--- name: nocobase-create-app description: Create a NocoBase 3 project to develop, locally, with `pnpm create @nocobase/app@beta`, configure it with `pnpm nocobase config init`, `config set` and `config check`, start it, and hand over to the application's own guidance. Use when the user asks to install, create, set up or try NocoBase to develop with, and the working directory holds no NocoBase application yet. Not for deploying to production, which belongs to the `nocobase-app-installer` Skill. Not for NocoBase 2 or the `nb` CLI, and not for work inside an existing application, which carries its own AGENTS.md and Skills. --- # 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: ```bash (cd && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 npm_config_registry="${NOCOBASE_REGISTRY:-https://registry.npmjs.org}" pnpm create @nocobase/app@beta --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. 1. **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`. 2. **`pnpm nocobase config init --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. 3. **`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. 4. **`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= --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 `admin@nocobase.com`) 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//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.