How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/nocobase/skills-v3 --skill nocobase-create-appBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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.jsonwith anocobasefield, next to anAGENTS.md— do not use this Skill. Read thatAGENTS.mdand continue from it. - NocoBase 3 is created with
pnpm create @nocobase/app@beta. Never fall back to NocoBase 2 instructions or thenbCLI, 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) andpnpm --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 24orfnm install 24, and for pnpmcorepack enable && corepack prepare pnpm@11 --activateornpm 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.
Choose the template
For a Professional or Enterprise edition application use the corresponding commercial template, pro or enterprise. Check access to the published version of @nocobase/app-template-pro or @nocobase/app-template-enterprise in the commercial registry as described below. When the selected generator lists the alias, use --template pro or --template enterprise with the requested template channel. An older generator can use the full package specifier with its explicit channel or version. Report an unavailable template to the user. These editions start with Default's registrations and preinstall commercial plugins as development dependencies. Both editions also preinstall the Dameng, KingbaseES and OceanBase database drivers. Postinstall synchronizes package Skills. With several drivers installed, pass the selected dialect explicitly, including pnpm nocobase config init --dialect sqlite for SQLite. First-time source initialization promotes a preinstalled commercial driver just as it does an open-source driver. With the updated application CLI, use pnpm nocobase plugin register <name> to enable a plugin, plugin unregister <name> to return it to development dependencies and keep its Skills, and plugin remove <name> for a full uninstall. Check the generated CLI help before using these commands on older releases. Choose multi-app, sub-app or multi-portal only for that specific application structure.
Use Default for an ordinary application, Examples for exploring bundled examples, and multi-portal when the user asks for one application with multiple business entry points. Use multi-app when the user asks for a Main application that manages independent child applications, and sub-app for a child application that such a Main deploys (see Continue by creating a child application). Multi-portal, multi-app and sub-app are commercial Pro templates. Multi-portal is not a tenant or process isolation mechanism. Keep the user's explicit template choice.
For Default and Examples, continue with Create below. For multi-portal, multi-app or sub-app, follow the commercial registry authentication steps below, verify access to the selected template package, then use that template's creation command instead of the public-registry command below.
Commercial multi-portal template
The template, portal management plugin and portal generator are commercial packages downloaded from https://pkg-v3.nocobase.com/. Before creating files, check the existing login and access to the requested version or channel:
npm whoami --registry=https://pkg-v3.nocobase.com/
npm view @nocobase/app-template-multi-portal@beta version --registry=https://pkg-v3.nocobase.com/Reuse valid credentials. If authentication is missing or expired, use the host's secure secret-input tool when available, or have the user log in through their terminal:
pnpm login --registry=https://pkg-v3.nocobase.com/ --scope=@nocobaseThis intentionally configures the @nocobase scope for the commercial registry. The password prompt takes the registry read token. Do not ask for the token in chat, print credentials, put them in command arguments, or copy them into project files. For secure file delivery, create an isolated npm user config outside the project (directory mode 700, file mode 600), containing the scoped registry and host-scoped token. Pass its path through NPM_CONFIG_USERCONFIG to every download/install command; never print its contents or change the global login. Remove that temporary copy after verification, and explain that future installs need the user's own login. After login, check package access again. A successful whoami alone does not establish download permission. On 401/403, resolve authentication or package access; on 404 or a missing channel, confirm the package/version is published and accessible. Stop creation if unavailable; do not silently select Default or claim an unreleased package is available. For an explicitly requested local preview registry, use that registry and its test credentials instead.
After access succeeds, create from the parent directory:
(cd <parent-directory> && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 NOCOBASE_REGISTRY=https://pkg-v3.nocobase.com/ npm_config_registry=https://registry.npmjs.org pnpm create @nocobase/app@beta <name> --template=multi-portal --template-tag=beta --json)multi-portal resolves to @nocobase/app-template-multi-portal and honors --template-tag. With a create-app version that predates the alias, use --template=@nocobase/app-template-multi-portal@beta instead; a full package specifier ignores --template-tag, so include the channel or explicit version in the specifier. Reuse the user's chosen registry/version rather than replacing it with these defaults. Registry selection is explicit even after login because create-app otherwise defaults to public npm. The generated .npmrc contains the registry URL, not credentials.
Create-app 0.1.0-beta.36 includes the private-registry installation fix: NOCOBASE_REGISTRY selects the template and the generated @nocobase scope, while third-party dependencies use the package manager's default registry. Keep that default public (or use the user's chosen public mirror); do not set it to a NocoBase-only private registry. The command installs dependencies automatically. Confirm ok: true and result.dependenciesInstalled: true, read the generated AGENTS.md, then continue with Configure and Start. Postinstall synchronizes Skills; run pnpm nocobase skills sync only if synchronization failed or its files are missing.
For an explicitly selected older create-app release such as 0.1.0-beta.35, use --no-install, then run the following in the generated app. Also use this recovery command when a previous attempt already created files but failed at dependency installation; do not create the project again:
(cd <parent-directory>/<name> && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 npm_config_registry=https://registry.npmjs.org pnpm install)Reuse the same authentication configuration for recovery. With --no-install, ok: true means scaffolding only and dependenciesInstalled is false. Confirm the project .npmrc has the intended @nocobase:registry URL without credentials. Once created, use the application's own AGENTS.md, .agents/rules/multi-portal.md and installed Skills for portal development. The portal command is pnpm create @nocobase/portal; generated portals start uninstalled and an authorized administrator installs them through System settings → Portals. Do not use pnpm create:module or replace business authorization with a grant to all users.
Commercial multi-app template
multi-app resolves to @nocobase/app-template-multi-app from the Pro registry and honors --template-tag. It creates Main only, with application management capabilities. It does not generate apps/sub or require an apps/ directory; independent child applications are added on demand.
Reuse the commercial registry login and scoped authentication procedure above, but verify the multi-app package itself before creating files:
npm view @nocobase/app-template-multi-app@beta version --registry=https://pkg-v3.nocobase.com/Check the selected generator's --help for multi-app in the supported template names. Once package access and alias support are confirmed, create Main from the parent directory:
(cd <parent-directory> && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 NOCOBASE_REGISTRY=https://pkg-v3.nocobase.com/ npm_config_registry=https://registry.npmjs.org pnpm create @nocobase/app@beta <name> --template multi-app --template-tag beta --json)A generator without this alias, including create-app 0.1.0-beta.36, can use --template=@nocobase/app-template-multi-app@beta instead; omit --template-tag because the package specifier already selects the channel. This still requires a published, accessible template. If the package or requested version is unavailable, report the blocker rather than substituting Default. For an explicitly requested unreleased preview, use the actual packed template artifact provided for that preview. Reuse the user's selected registry and version.
Confirm ok: true and result.dependenciesInstalled: true, read the generated AGENTS.md, then follow Configure and Start below. Once Main is running, offer the child-creation guide below before the final handover. Configure an available Releases App Host before creating managed instances; starting Main alone does not enable child deployment.
Continue by creating a child application
After Main is configured and running, ask whether the user wants to create a child now. Do not create one automatically. If they decline, finish with Main's handover. If they agree, offer <main-directory>/packages/child-app as the default and accept a user-specified directory; resolve relative paths from Main. Reuse explicit choices instead of asking again. Require a new or empty target and never overwrite an existing application.
Before creation, ask whether the child needs platform-wide SSO. Independent login is the default. Selecting SSO authorizes installing and configuring the commercial @nocobase/app-plugin-platform-sso package; merely requesting a child does not. Reuse the commercial registry authentication procedure and verify access to a compatible plugin version before installation. If access or required SSO configuration is unavailable, report the blocker rather than silently changing the login choice.
When the user selected SSO, prefer the commercial sub-app template (@nocobase/app-template-sub-app), which already registers platform SSO and preinstalls the deploy CLI extension: verify it with npm view @nocobase/app-template-sub-app@beta version --registry=https://pkg-v3.nocobase.com/ and check that the generator's --help lists sub-app, then use --template sub-app with NOCOBASE_REGISTRY=https://pkg-v3.nocobase.com/ in the command below and skip the separate SSO plugin installation. If the template or alias is unavailable, use the Default procedure below. Otherwise create the child as an ordinary Default application, not another multi-app Main. Create its parent directory when needed and run from that parent with the target's basename; do not pass a slash-containing path or . as the application name. For the default location:
mkdir -p <main-directory>/packages
(cd <main-directory>/packages && PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 pnpm create @nocobase/app@beta child-app --template default --template-tag beta --no-install --json)Use --no-install so the workspace boundary can be checked before dependency installation; dependenciesInstalled: false is expected at this step. Main's default workspace includes packages/*. For a child nested under Main, preserve existing workspace settings and exclude that exact child from Main's pnpm-workspace.yaml package globs (for the default directory, append !packages/child-app). Keep the child's generated pnpm-workspace.yaml and its own lockfile; do not add it as a Main dependency. From the child directory, verify pnpm root -w points to the child's node_modules before running pnpm install. For a custom location, check any enclosing workspace and establish the same independent boundary. Do not relocate the user's requested target silently.
Read the child's own AGENTS.md, install dependencies there, and follow Configure and Start for that child. Keep its configuration, database and storage independent from Main, and select a different local port. Keep child source and runtime files out of Main's deployment archive; Main consumes the child's separately built archive.
If the user selected SSO, configure the child's @nocobase registry and reuse secure credentials before running pnpm add @nocobase/app-plugin-platform-sso@<compatible-version> in the child. NOCOBASE_REGISTRY alone does not configure pnpm add. Synchronize Skills if the installed plugin's guidance is missing, then follow nocobase-app-plugin-platform-sso for server/client/config registration and login verification, and nocobase-app-plugin-multi-app in Main for the platform-side setup. Installation alone does not enable SSO. Resolve the platform issuer, child origin/callback, application/client identity and securely supplied credentials; retain local recovery login unless the user explicitly requests a different policy. Without SSO, keep ordinary local authentication and do not install that plugin.
Verify child startup and, when selected, the actual SSO flow before reporting them as working. Report Main and child directories, URLs, selected login mode and any remaining setup. Offer the installed multi-app Skill's next steps—build the child's dist.tar.gz, upload and publish a version in Main—without automatically deploying it.
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=https://registry.npmjs.org pnpm create @nocobase/app@beta <name> --template-tag=beta --json)- Open-source NocoBase 3 packages,
@nocobase/create-appincluded, are published to public npm; commercial packages require the private registry described above.NOCOBASE_REGISTRYselects the template registry and a non-public@nocobaseoverride in the generated.npmrc. Since create-app0.1.0-beta.36, automatic installation leaves third-party dependencies on the package manager's default registry. Keep the user's persistent pnpm configuration unchanged; preserve an explicitly chosen public mirror. For a local snapshot, authenticate/configure its@nocobasescope before launchingpnpm create, so the creation tool itself also comes from that snapshot. - Use the
betachannel 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 tolatestifbetacannot be resolved. An explicit version or local snapshot requested by the user takes precedence. NOCOBASE_REGISTRYis set only when the shell is pointed at another registry, such as an unreleased snapshot;create-appreads it too.PNPM_CONFIG_MINIMUM_RELEASE_AGE=0lets pnpm install versions published minutes ago.--jsonnever prompts. It prints one JSON document on stdout and progress on stderr, so parse stdout only. It is the envelope everypnpm nocobase … --jsoncommand prints:oksays whether creation worked,resultholds what it produced, and a failure'serror.code,error.messageanderror.detailssay where it stopped. create-app 0.1.0-beta.23 and earlier print a flat result instead, withstatussuccessorerrorandstage,message,directoryandnextCommandsat the top level; read the same fields there.- The default template is the one to develop an application from and needs no
--templateflag; keep--template-tag=beta. Add--template=exampleswhen 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, for SQLite run pnpm nocobase config init --dialect sqlite, pnpm nocobase config check, then pnpm dev. Reuse any database choice already made in the session. For a disposable installation smoke test, state that SQLite will be used and proceed; for a lasting project with no database choice, ask before configuring it, 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 session’s choice, SQLite for an unspecified disposable smoke test, or ask for a lasting project. Default preinstalls SQLite, PostgreSQL, MySQL, SQL Server and Oracle in
devDependencies. The current application CLI promotes the selected preinstalled driver todependenciesand updates the lockfile when writing the initial configuration. For older CLIs or additional connections, move the corresponding entry with its original version range and runpnpm install. Preserve drivers for other active connections. - `pnpm nocobase config init --dialect <dialect> --json` writes
config.ymlfrom the application'sconfig.example.yml, with generated secrets.
- When the driver is missing it writes nothing and fails with
error.codeDRIVER_MISSING;error.suggestions[0].runis thepnpm addthat supplies it. Run that, then runconfig initagain. - An application that is already configured is reported with
status: "success-noop", so re-running the sequence is safe. result.requiredSettingslists the connection settings still at a placeholder.
- `pnpm nocobase config set key=value … --json` sets each of the
requiredSettings, for exampledatabase.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 validates configuration without starting the application; inspect each connection status. A SQLite connection reported as
skippedis not proof that the native driver loads: application startup and migrations must succeed too. A failure haserror.codeCONFIG_INVALIDand its findings inerror.details.findings; each names its key and, where there is one, afixto 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.
Installation smoke tests
For an explicitly requested installation test, use published packages in a fresh disposable directory and record resolved versions. Verify dependency installation, configuration, successful server startup/migrations, and an HTTP response at the actual application entry. Respect the user's LAN-only preference and configure the public origin to the address used for login; do not infer login success from a homepage HTTP 200.
For multi-portal smoke tests, also exercise pnpm create @nocobase/portal@beta <name> with the same scoped registry/authentication, verify Client/Server registration, sign in through the actual LAN origin, and verify the portal is initially uninstalled and can be installed by the administrator. Read the authenticated API document for request contracts; portal installation also requires an Idempotency-Key in <13-digit Unix milliseconds>.<UUID> form. Retain one key for retries of the same request. Check anonymous management access is rejected, and run pnpm build to validate the generated template and portal together. Do not add a sample portal to an ordinary new project unless requested.
Distinguish HTTP/API verification from browser interaction, and report any workaround separately from the original command's result. A working app after recovery does not mean one-command creation passed. Clean up temporary credentials and session cookies, leaving the requested preview available.
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.ymlor any secret it contains. - Do not pass
--force, deleteconfig.ymlor drop a database to make a step pass.config init --forcereplaces 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.initialAdminin the configuration: by default the usernamenocobase(emailadmin@nocobase.com) with the passwordadmin123. 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 devin the application directory, run in their own terminal or by the next session. - Where to continue. The application's
AGENTS.mdand 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-developmentSkill 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 && claudefor 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-deploymentSkill builds its deployment archive, and the globalnocobase-app-installerSkill 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. |
Third-party package (for example @tailwindcss/vite) returns 404 from pkg-v3 | Keep @nocobase:registry private and run npm_config_registry=https://registry.npmjs.org PNPM_CONFIG_MINIMUM_RELEASE_AGE=0 pnpm install in the existing app. Use create-app 0.1.0-beta.36 or a later release containing the fix for new apps; use --no-install only when deliberately retaining an older affected version. |
| 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 | For SQLite run pnpm nocobase config init --dialect sqlite --json, then pnpm nocobase config check --json, and follow the result. |
For an application walkthrough, see https://github.com/nocobase/nocobase/blob/v3/docs/docs/en/capabilities/quick-start.md.