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.

The full install guide and integration prompts unlock after purchase.