Every package published from this repository lives here, grouped by what it is rather than by what it is named. The grouping is a convention for readers; pnpm resolves packages by name, so moving a package between these directories changes nothing about how it is depended on or filtered.

Directory	What belongs here
`libs/`	Runtime libraries that solve one problem and know nothing about NocoBase applications
`app/`	The application runtime itself — what an application is built out of
`plugins/`	Application plugins that ship as product features
`examples/`	Application plugins that exist to demonstrate a capability
`templates/`	Complete applications that `create-app` scaffolds from
`apps/`	Complete product applications this repository builds and deploys itself
`tools/`	Development and build tooling, not shipped inside an application

`libs/`

Standalone libraries. Each solves one problem — storage, caching, queuing, logging — and depends on nothing above it. A library here should be usable outside NocoBase without pulling in an application runtime.

caching wraps a cache store behind a small interface. i18n (@nocobase/i18n) provides the translation mechanism: namespaces, resource loading, and the React and Node bindings, with no routes and no notion of a user.

`app/`

The runtime an application is assembled from. app-server composes configuration, plugins, and providers into a running server; app-skills publishes the shared agent guidance synchronized into generated applications. app-cli is the application's command line — the runtime commands a deployment runs, plugin management, and the dev and build tooling, which it keeps out of a deployment as optional peers.

These packages know what a NocoBase application is, which is what separates them from libs/.

`plugins/`

Plugins that contribute real product functionality: a feature is enabled by installing one. app-plugin-file provides file Repository services, route factories, and editable Registry UI; app-plugin-authentication adds sign-in.

Create one with pnpm plugin:create, which scaffolds it here.

`examples/`

Plugins whose purpose is to show how something works. app-plugin-routes-example demonstrates server routes alongside lazily loaded client routes.

They are published and installable like any other plugin — the difference is intent, not packaging. An example is written to be read.

`templates/`

Complete, runnable applications. create-app downloads one and scaffolds a project from it, so a template is published as its own source rather than as a built library.

app-template-default is what pnpm create @nocobase/app produces. app-template-examples combines application-owned article management with installable capability examples and demonstration data.

For everyday development and exploring examples in this repository, run pnpm examples:dev from the repository root. Each template has explicit root commands:

Template	Development	Build	Start the built application
Examples	`pnpm examples:dev`	`pnpm examples:build`	`pnpm examples:start`
Default	`pnpm default:dev`	`pnpm default:build`	`pnpm default:start`

Inside a template's own directory, use pnpm dev, pnpm build, and pnpm start.

`apps/`

Complete applications that are products in their own right rather than starting points. studio (@nocobase/studio) is NocoBase Studio, the AI application workspace that assembles the projects, agents, knowledge and releases plugins. An application here is published as its own source, like a template, so it can be installed and built elsewhere, but create-app never scaffolds from it and nothing depends on it.

It is not kept in step with the templates: it takes a newer template through its nocobase-app-upgrade Skill, as any generated application does. Its migrations are immutable history from the moment they merge, because installations of it keep their data across updates.

`tools/`

Everything used to develop and build the packages above, none of which ends up in a deployed application's dist/. dev-config holds the shared TypeScript, ESLint, Prettier, Vitest, and Vite presets that every other package extends; it is also a development dependency of every template, so a generated application installs it for its own configuration and for nocobase build, which loads it as an optional peer of app-cli. create-app is the scaffolder that turns a template into a project. studio-cli publishes nb-studio, NocoBase Studio's command line, on its own: @nocobase/app-cli-client with Studio's brand and Skill, so a machine can install it from npm instead of from a Studio server.

Adding a package

Pick the directory by the questions above, then follow the conventions in the repository root AGENTS.md: extend a preset from @nocobase/dev-config instead of copying a configuration, start at version 0.0.1 with publishConfig.access set to "public", declare files, and put tests in a tests/ directory at the package root.