{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@nocobase/acl": ["nocobase-source/packages/core/acl/src"],
      "@nocobase/database": ["nocobase-source/packages/core/database/src"],
      "@nocobase/server": ["nocobase-source/packages/core/server/src"]
    }
  }
}

3. Install workspace dependencies from the source root:

cd nocobase-source
npm install
npm run build   # or: npx lerna run build

4. Set required environment variables before starting the server:

DB_DIALECT=sqlite         # or postgres / mysql / mariadb
DB_STORAGE=./storage/db.sqlite
APP_KEY=your-secret-key-here
APP_PORT=13000

5. Point your server entry file to @nocobase/server (see examples below).

Public API

Application (from @nocobase/server)

import Application from '@nocobase/server';

const app = new Application({
  database: { dialect: 'sqlite', storage: process.env.DB_STORAGE },
  plugins: [],
});

The Application class is the central server orchestrator. Use it to bootstrap the NocoBase backend, register plugins, and invoke runAsCLI(argv) for CLI-driven startup as shown in examples/index.ts.

Database (from @nocobase/database)

import Database from '@nocobase/database';

const db = new Database({
  dialect: 'sqlite',
  storage: './storage/db.sqlite',
});
console.log('Table prefix:', db.getTablePrefix());

Database provides the ORM abstraction over SQL backends. Use it standalone to inspect or migrate schema, or pass it as a dependency when constructing Application. It exposes getTablePrefix() and collection/repository APIs.

ACL exports (from @nocobase/acl)

import { ACL, ACLRole, ACLResource, SkipMiddleware } from '@nocobase/acl';

const acl = new ACL();
acl.define({ role: 'admin', actions: { '*': true } });

The @nocobase/acl package exports ACL, ACLRole, ACLResource, ACLAvailableAction, ACLAvailableStrategy, SkipMiddleware, and error types including NoPermissionError. Use it to define role-based access control policies that the server middleware enforces on every incoming action.

getCustomMDXComponent (from docs/theme/index.tsx)

import { getCustomMDXComponent } from './docs/theme';

const components = getCustomMDXComponent();
// components includes: h1 (with LlmsContainer), PluginCard, Badge, Tabs, Tab, NoSSR

Used inside the RSPress documentation site to override default MDX component rendering. It wraps h1 with LLMS copy/view controls and injects PluginInfo and ProvidedBy metadata beneath every page title.

Working examples

Scenario - Bootstrapping a minimal NocoBase server

A developer wants to start a NocoBase server process from a custom entry point, loading a single plugin and exposing the REST API.

import Application from '@nocobase/server';

const app = new Application({
  database: {
    dialect: process.env.DB_DIALECT as any || 'sqlite',
    storage: process.env.DB_STORAGE || './storage/db.sqlite',
  },
  plugins: ['nocobase'],
});

app.runAsCLI(process.argv);

Scenario - Standalone database inspection

A developer needs to inspect table prefix configuration for a migration script without running the full application server.

import Database from '@nocobase/database';

async function inspect() {
  const db = new Database({
    dialect: 'postgres',
    host: process.env.DB_HOST || 'localhost',
    port: Number(process.env.DB_PORT) || 5432,
    database: process.env.DB_DATABASE || 'nocobase',
    username: process.env.DB_USER || 'postgres',
    password: process.env.DB_PASSWORD || '',
  });

  console.log('Table prefix:', db.getTablePrefix());
  await db.close();
}

inspect().catch(console.error);

Scenario - Defining ACL roles programmatically

A developer is building a custom plugin and needs to declare role permissions at boot time using the ACL package directly.

import { ACL, ACLAvailableAction } from '@nocobase/acl';

const acl = new ACL();

acl.setAvailableAction('view', new ACLAvailableAction('view', { displayName: 'View' }));
acl.setAvailableAction('create', new ACLAvailableAction('create', { displayName: 'Create' }));
acl.setAvailableAction('update', new ACLAvailableAction('update', { displayName: 'Update' }));

const adminRole = acl.define({ role: 'admin' });
adminRole.grantAction('orders:view');
adminRole.grantAction('orders:create');

const guestRole = acl.define({ role: 'guest' });
guestRole.grantAction('orders:view');

console.log('Admin can create orders:', acl.can({ role: 'admin', resource: 'orders', action: 'create' }));
console.log('Guest can create orders:', acl.can({ role: 'guest', resource: 'orders', action: 'create' }));

File walkthrough

• .github/ - Contains all GitHub Actions workflows for CI testing (backend, frontend, Windows), Docker image builds, changelog generation, release automation, and PR review bots.
• .vscode/ - VS Code debugger launch configurations for running server processes directly from the IDE.
• docker/ - Per-database Docker Compose files and the main docker-entrypoint.sh startup script for container deployments.
• docs/ - Full RSPress documentation site: source MDX content, the custom RSPress theme (docs/theme/), plugin reference pages, and deployment scripts.
• examples/ - Minimal runnable scripts that demonstrate instantiating Application or Database and calling their primary methods.
• locales/ - JSON locale bundles consumed by the platform's i18n runtime.
• packages/ - The heart of the monorepo: all @nocobase/* core libraries and bundled plugins.
• lerna.json - Declares workspace versioning strategy and package globs for Lerna.
• package.json - Root manifest; defines workspace paths, top-level scripts (build, test, lint), and shared dev tooling.
• tsconfig.json - Monorepo-wide TypeScript settings; individual packages extend this.
• tsconfig.server.json - TypeScript settings restricted to server-side compilation (excludes browser-only packages).
• playwright.config.ts - Configuration for Playwright end-to-end tests run against a live NocoBase instance.
• docker-compose.yml - Convenience Compose file for spinning up a full NocoBase stack locally with a single command.

Common pitfalls and fixes

• DB_DIALECT not set causes SQLite fallback silently: Always explicitly set DB_DIALECT and validate at startup; omitting it with a postgres-only schema will produce confusing table-not-found errors.
• Monorepo build order matters: Run npx lerna run build --sort rather than building packages in parallel; @nocobase/server depends on @nocobase/database and @nocobase/acl being compiled first.
• APP_KEY must be stable across restarts: If APP_KEY changes between restarts, all existing session tokens are invalidated; store it in a .env file that is never regenerated automatically.
• ESM/CJS interop with RSPress theme: docs/theme/index.tsx uses ESM-only imports from @rspress/core; do not attempt to require() it from a CommonJS context - use dynamic import() or set "module": "ESNext" in the consuming tsconfig.
• getTablePrefix() returns an empty string by default: When writing raw queries in migrations, guard against an empty prefix rather than assuming a non-empty value.
• Docker volume permissions on Linux: The SQLite storage path inside the container must be owned by the process user; mount volumes with explicit uid/gid or pre-create the directory with correct permissions to avoid SQLITE_CANTOPEN errors.

Vibe-coding prompt template

I have the NocoBase monorepo source in ./nocobase-source/ and a USAGE.md
integration guide at ./USAGE.md. The upstream package is `nocobase`.

Please help me integrate NocoBase into my existing Node.js/TypeScript project
step by step:

1. Read USAGE.md fully before writing any code.
2. Add the necessary tsconfig path aliases for @nocobase/acl,
   @nocobase/database, and @nocobase/server pointing into
   ./nocobase-source/packages/core/.
3. Create a server entry file (src/server.ts) that constructs an Application
   instance using environment variables for DB_DIALECT, DB_STORAGE/DB_HOST,
   and APP_KEY, registers my custom plugin, and calls runAsCLI.
4. Create an ACL setup module (src/acl-setup.ts) that defines at least two
   roles (admin and viewer) using the ACL class from @nocobase/acl, granting
   appropriate actions.
5. Add a docker-compose.yml that references the ./nocobase-source/docker/
   configurations for the correct database dialect.
6. Show me how to run the test suite for only the backend packages using the
   lerna scripts defined in ./nocobase-source/package.json.

Use only exports visible in USAGE.md and the file excerpts. Do not invent
APIs. Show complete, runnable TypeScript files with all imports.

License and credit

NocoBase is dual-licensed under AGPL-3.0 and the NocoBase Commercial License. See source/LICENSE-APACHE.txt and source/LICENSE.txt for full terms. Commercial use beyond AGPL permissions requires a separate license from NocoBase Co., Ltd.

Upstream repository and homepage: https://www.nocobase.com/ GitHub: https://github.com/nocobase/nocobase

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

SaaS, AI & Subscription Products

$3