{
  "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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.

SaaS, AI & Subscription Products

3 US$