Project structure

Directory overview

Creating an app gives you source code you can edit directly. The following shows common development locations in the default application template. Configuration, installed dependencies and build output appear after their respective setup steps.

my-app/
├── client/              # Pages, components and client logic
├── server/              # APIs and business services
├── database/            # Migrations and seeds, grouped by connection
├── cli/                 # Application commands and CLI plugins
├── tests/               # Tests and test helpers
├── public/              # Static assets
├── packages/            # Local workspace packages (optional)
├── .agents/
│   ├── rules/           # Project-owned Agent rules
│   └── skills/          # Synchronized dependency Skills (generated)
├── AGENTS.md            # Agent guidance entry
├── config.example.yml   # Configuration example
├── config.yml           # Local configuration (generated during setup)
├── package.json         # Scripts and dependencies
├── pnpm-lock.yaml       # Resolved dependency versions
├── pnpm-workspace.yaml  # Workspace settings
├── node_modules/        # Installed dependencies (generated)
├── dist/                # Build output (generated)
└── storage/             # Runtime data

Directories vary with the template version and application features. Create optional directories such as packages/ when needed, rather than adding empty directories to match the tree.

Where pages, APIs and data belong

Connect pages and APIs to their registration entries: adding a file alone does not make it accessible. UI source installed in client/extensions/ also belongs to the application and connects to pages or components through imports.

database/ groups resources by connection name; main is the default connection. Keep migrations that have already run and add new ones for later schema changes. See Tables and initial data for implementation details.

For example, customer management typically involves a table migration, API routes, a page and the corresponding registration files. Follow Develop your first feature to see how these locations fit a working feature.

Configuration, dependencies and plugins

Configuration files

Use config.yml to change connection details for the current environment. Update definitions in server/config/ when adding configuration options for your business logic. See Application configuration for loading behavior and commands.

Dependencies and plugin registration

package.json contains development, test and build scripts alongside dependency declarations. pnpm-lock.yaml records resolved dependency versions and belongs in source control.

The template provides capabilities such as users, authentication, authorization and files through plugins. package.json shows which packages are installed; the registration files show which contributions are connected:

A plugin may not provide all three entries, and some packages supply only development Skills. Installing dependencies, registering plugins and integrating pages are separate steps. See Manage plugins for instructions and the Plugin index for individual capabilities.

Keep local plugins or shared packages in packages/ and configure workspace package directories in pnpm-workspace.yaml. You can also maintain a UI Registry package there when distributing UI source assets independently. See Project directory and file conventions for the detailed structure.

Where tests belong

Tests live in tests/, organized by the code they verify:

Run pnpm test from the application root for Vitest tests. Browser tests use pnpm test:e2e and require a running application and sign-in details as specified in the test configuration. See Testing for setup instructions.

Existing projects may use different directories; follow their vitest.config.ts and playwright.config.ts. Check the actual test count in the report: a successful exit with no tests does not verify the feature.

Guidance the agent reads

AGENTS.md is the entry point for application development guidance. Distinguish project-owned conventions from Skills supplied by dependencies:

Add business conventions to the project guidance as described in Continue developing your app. Run pnpm nocobase skills sync in the application directory to refresh Skills from dependencies; see the CLI reference for more options.

Generated files and runtime data

The following are not maintained as business source code:

The connection configuration determines where SQLite stores its database, which may also be in the application root. Do not delete database files or business data in storage/ as though they were build caches. See Project directory and file conventions for the complete path reference.