Required dependencies

npm install express cors ejs
npm install @nestjs/core @nestjs/common @nestjs/platform-express @nestjs/websockets
npm install knex
npm install nocodb-sdk
npm install passport passport-jwt passport-local
npm install ioredis
npm install multer
npm install nodemailer
npm install jsonwebtoken
npm install dotenv

TypeScript and build tools:

npm install --save-dev typescript ts-node @types/node @types/express @types/cors tsconfig-paths

No native build steps are required. If using the Redis cache backend, a running Redis instance is needed (see env vars below).

Project setup

1. Copy the source/ directory into your project root (e.g. ./nocodb-backend/).

2. Set path aliases in your tsconfig.json to match source/tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["src/*"]
    },
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "commonjs",
    "target": "ES2019"
  }
}

3. Register tsconfig-paths at runtime (required for the ~/ alias):

import 'tsconfig-paths/register';

4. Set required environment variables in .env or your shell:

NC_DB="pg://localhost:5432?u=postgres&p=password&d=nocodb"  # or leave unset for SQLite
NC_AUTH_JWT_SECRET="your-jwt-secret"
PORT=8080

# Optional Redis cache
NC_REDIS_URL="redis://localhost:6379"

# Optional file upload limits
NC_ATTACHMENT_FIELD_SIZE=20971520
NC_MAX_ATTACHMENTS_ALLOWED=10
NC_FORM_FIELD_MAX_SIZE=10485760

# Optional token expiry
NC_REFRESH_TOKEN_EXP_IN_DAYS=30

5. Use src/main.ts as your entry point, or embed Noco into an existing Express app (see examples below).

Public API

Noco

import Noco from './src/Noco';
// or
import { Noco } from './src/index';

class Noco {
  static init(
    options: Record<string, any>,
    httpServer: http.Server,
    app: express.Application
  ): Promise<express.Router>;
}

The central class. Call Noco.init() after your HTTP server starts to mount the entire NocoDB REST API as an Express router. Returns a promise resolving to the configured router. Used in main.ts to attach NocoDB to any Express app.

NC_LICENSE_KEY / constants

import {
  NC_LICENSE_KEY,
  NC_APP_SETTINGS,
  NC_ATTACHMENT_FIELD_SIZE,
  NC_MAX_ATTACHMENTS_ALLOWED,
  NC_REFRESH_TOKEN_EXP_IN_DAYS,
  V1_V2_DATA_PAYLOAD_LIMIT,
  V3_DATA_PAYLOAD_LIMIT,
  V3_META_REQUEST_LIMIT,
  MAX_NESTING_DEPTH,
} from './src/constants';

Environment-driven constants controlling upload limits, pagination caps, nesting depth, and token expiry. Import these anywhere in your application instead of re-reading process.env to ensure consistent behavior with NocoDB's internal logic.

CTEGenerator

import { CTEGenerator } from './src/db/cte-generator';
import type { NcContext } from 'nocodb-sdk';
import type CustomKnex from './src/db/CustomKnex';

class CTEGenerator {
  constructor(info: { context: NcContext; knex: CustomKnex });
  async getClientType(): Promise<ClientType>;
  async baseUser(param: { context?: NcContext; include_ws_deleted?: boolean }): Promise<ICteBlock>;
  getExistingAlias(alias: string): ICteBlock;
}

Generates SQL Common Table Expressions for complex queries (user aggregations, LTAR links, lookups). Use when building custom query pipelines that need to reuse NocoDB's meta-aware CTE blocks against the underlying Knex connection.

Working examples

Scenario - Embed NocoDB into an existing Express app

Mount NocoDB as a sub-application within an existing Express server, preserving your own routes alongside NocoDB's API.

import 'tsconfig-paths/register';
import http from 'http';
import express from 'express';
import cors from 'cors';
import Noco from './nocodb-backend/src/Noco';

const app = express();
app.enable('trust proxy');
app.disable('etag');
app.use(cors({ exposedHeaders: 'xc-db-response' }));
app.set('view engine', 'ejs');

// Your own routes
app.get('/health', (_req, res) => res.json({ status: 'ok' }));

const server = http.createServer(app);

server.listen(process.env.PORT || 8080, async () => {
  // Mount NocoDB — returns an Express router handling /api/v1, /api/v2, etc.
  const nocoRouter = await Noco.init({}, server, app);
  app.use(nocoRouter);
  console.log('Server ready on port', process.env.PORT || 8080);
});

Scenario - Read NocoDB constants to validate incoming payloads

Use the exported constants to enforce the same limits NocoDB uses internally before forwarding data to the API layer.

import {
  NC_ATTACHMENT_FIELD_SIZE,
  NC_MAX_ATTACHMENTS_ALLOWED,
  NC_NON_ATTACHMENT_FIELD_SIZE,
  V3_DATA_PAYLOAD_LIMIT,
} from './nocodb-backend/src/constants';

function validateBulkPayload(records: unknown[]): void {
  if (records.length > V3_DATA_PAYLOAD_LIMIT) {
    throw new Error(
      `Bulk insert limited to ${V3_DATA_PAYLOAD_LIMIT} records per request (V3 API).`
    );
  }
}

function validateAttachmentSize(sizeBytes: number, count: number): void {
  if (sizeBytes > NC_ATTACHMENT_FIELD_SIZE) {
    throw new Error(`Attachment exceeds max size of ${NC_ATTACHMENT_FIELD_SIZE} bytes.`);
  }
  if (count > NC_MAX_ATTACHMENTS_ALLOWED) {
    throw new Error(`Cannot attach more than ${NC_MAX_ATTACHMENTS_ALLOWED} files.`);
  }
}

validateBulkPayload(new Array(5).fill({}));          // ok
validateAttachmentSize(5 * 1024 * 1024, 3);          // ok

Scenario - Standalone server matching the default main.ts bootstrap

Replicate the exact startup from src/main.ts for a clean standalone deployment.

import 'tsconfig-paths/register';
import 'dotenv/config';
import cors from 'cors';
import express from 'express';
import Noco from './nocodb-backend/src/Noco';

const server = express();
server.enable('trust proxy');
server.disable('etag');
server.disable('x-powered-by');
server.use(cors({ exposedHeaders: 'xc-db-response' }));
server.set('view engine', 'ejs');

async function bootstrap() {
  const httpServer = server.listen(process.env.PORT || 8080, async () => {
    server.use(await Noco.init({}, httpServer, server));
    console.log(`NocoDB running on http://localhost:${process.env.PORT || 8080}`);
  });
}

bootstrap().catch((err) => {
  console.error('Failed to start NocoDB:', err);
  process.exit(1);
});

File walkthrough

• src/Noco.ts - Core class; bootstraps NestJS application and returns an Express-compatible router.
• src/main.ts - Minimal Express entrypoint demonstrating server creation and Noco.init() usage.
• src/index.ts - Package export; exposes Noco as both default and named export.
• src/app.module.ts - Root NestJS module; imports all feature modules.
• src/app.config.ts - Top-level configuration object for NestJS app factory.
• src/constants/index.ts - All environment-driven runtime constants (sizes, limits, keys).
• src/controllers/ - NestJS controllers mapping HTTP routes to service calls; organized by domain (bases, tables, data, auth, attachments, etc.).
• src/services/ - Business logic layer; controllers delegate here.
• src/models/ - Active-record-style data models backed by the meta database via Knex.
• src/db/ - Low-level DB layer: CustomKnex wrapper, field handlers per UI type and DB client, CTE generator, SQL view builders.
• src/meta/ - MetaService for all reads/writes to NocoDB's internal metadata tables.
• src/modules/ - NestJS feature module groupings (auth, global, jobs, etc.).
• src/cache/ - NocoCache abstraction with RedisCacheMgr and RedisMockCacheMgr implementations.
• src/guards/ - Route guards enforcing JWT and API-token authentication.
• src/middlewares/ - Request middleware (tenant context, rate limiting).
• src/helpers/ - NcError error factory and catchError async wrapper.
• src/plugins/ - Pluggable storage backends (S3, Minio, local) and notification drivers.
• src/gateways/ - Socket.IO gateway for broadcasting real-time table/record events.
• src/strategies/ - Passport strategies (JWT, local email/password).
• src/version-upgrader/ - Sequential migration scripts run on NocoDB startup.
• src/utils/ - General-purpose helpers (date parsing, string utils, IP tools).
• src/mcp/ - Model Context Protocol integration layer.
• docker/ - start.sh, start-litestream.sh, and litestream.yml for containerized deployments with SQLite WAL replication.
• build-utils/ - Build-time scripts for alias resolution and integration bundling; not needed at runtime.

Common pitfalls and fixes

• tsconfig-paths not registered: The ~/ alias fails at runtime with "Cannot find module". Fix: add import 'tsconfig-paths/register' as the very first line of your entrypoint before any other imports.
• emitDecoratorMetadata missing: NestJS DI silently breaks with TypeError: Reflect.metadata is not a function. Fix: ensure "emitDecoratorMetadata": true and "experimentalDecorators": true are in tsconfig.json, and that reflect-metadata is imported once at startup.
• NC_REFRESH_TOKEN_EXP_IN_DAYS set to 0 or non-numeric: The constants module throws on import with "NC_REFRESH_TOKEN_EXP_IN_DAYS must be a positive number". Fix: either unset the env var (defaults to 30) or set it to a positive integer.
• SQLite default path collision: Without NC_DB, NocoDB writes its meta SQLite file to the working directory. Fix: set NC_DB explicitly or mount a named Docker volume to /usr/app/data/.
• Redis URL set but Redis unreachable: Cache manager will throw on first cache operation and crash the server. Fix: only set NC_REDIS_URL when Redis is actually reachable; omit it for in-memory fallback.
• ESM/CJS interop with cors and express: When targeting ESM output, import cors from 'cors' may fail. Fix: keep "module": "commonjs" in tsconfig.build.json or use createRequire for CJS-only packages.

Vibe-coding prompt template

I have the NocoDB backend source in the `source/` directory.
Read `source/USAGE.md` for full integration instructions.
The upstream package is `nocodb-root` (NocoDB NestJS/Express backend).

My project is a Node.js/TypeScript Express app at `src/server.ts`.

Please help me:
1. Copy `source/src/` into my project and wire the `~/` path alias in `tsconfig.json`.
2. Register `tsconfig-paths` and `reflect-metadata` at the top of `src/server.ts`.
3. Mount `Noco.init()` from `source/src/Noco.ts` onto my existing Express `app` after the HTTP server starts.
4. Add all required environment variables (NC_DB, NC_AUTH_JWT_SECRET, PORT) to my `.env` file.
5. Import and use the constants from `source/src/constants/index.ts` to validate attachment uploads in my custom upload route.
6. Show me how to run the final server with `ts-node -r tsconfig-paths/register src/server.ts`.

Work step by step. Use only exports documented in `source/USAGE.md`. Do not invent new APIs.

License and credit

NocoDB is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See source/LICENSE if present, or refer to the official NocoDB repository for the full license text. This block is derived from the nocodb/nocodb monorepo, packages/nocodb.

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.