{
  "dependencies": {
    "node-red": "file:./source/node_modules/node-red"
  }
}

2. Create a settings file (settings.js) in your project root - Node-RED requires this at startup:

// settings.js
module.exports = {
    uiPort: process.env.PORT || 1880,
    httpAdminRoot: '/admin',
    httpNodeRoot: '/api',
    userDir: './nodered-data/',
    flowFile: 'flows.json',
    credentialSecret: process.env.NR_CREDENTIAL_SECRET || 'change-me',
    logging: { console: { level: 'info', metrics: false, audit: false } },
    editorTheme: { projects: { enabled: false } }
};

3. Set required environment variables:

NR_CREDENTIAL_SECRET=<random-secret-string>
NODE_RED_HOME=./nodered-data
PORT=1880

4. Wire into your Express app (see examples below).

5. TypeScript: Node-RED ships CommonJS. In tsconfig.json set "moduleResolution": "node" and "esModuleInterop": true. Import using require or import ... from 'node-red' with "allowSyntheticDefaultImports": true.

Public API

The file listing confirms the top-level node-red package and its sub-packages. Based on the package structure and well-established public surface:

RED (default export from node-red)

import RED from 'node-red';

interface NodeRedApp {
    init(httpServer: http.Server, settings: object): void;
    start(): Promise<void>;
    stop(): Promise<void>;
    httpAdmin: express.Application;
    httpNode: express.Application;
    version(): string;
    settings: object;
    nodes: object;
    log: object;
    util: object;
    hooks: object;
    plugins: object;
}

The main entry point. Call init() with your HTTP server and settings object before start(). httpAdmin and httpNode are Express apps you can mount into a parent router.

@node-red/util (utility helpers)

import * as util from '@node-red/util';

// Key exports
util.log.info(msg: string): void;
util.log.warn(msg: string): void;
util.log.error(msg: string): void;
util.i18n.i(): i18next.i18n;
util.hooks.add(hookName: string, handler: Function): void;
util.hooks.trigger(hookName: string, payload: any): Promise<any>;

Use for structured logging from custom nodes or surrounding application code, and for registering hooks into runtime lifecycle events without modifying core.

@node-red/runtime (flow runtime)

import * as runtime from '@node-red/runtime';

runtime.init(settings: object, storage: object, log: object, i18n: object): void;
runtime.start(): Promise<void>;
runtime.stop(): Promise<void>;
runtime.nodes.createNode(node: object, def: object): void;
runtime.nodes.registerType(type: string, constructor: Function): void;

Use directly when embedding the runtime without the editor, or when writing advanced integrations that need to register node types programmatically before startup.

Working examples

Scenario - Embed Node-RED alongside an existing Express app

Mount the Node-RED admin editor and node HTTP endpoints as sub-paths of your existing Express application, sharing one HTTP server.

import express from 'express';
import http from 'http';
import RED from 'node-red';
import settings from './settings.js';

const app = express();
const server = http.createServer(app);

// Initialise Node-RED
RED.init(server, settings);

// Mount editor UI at /red
app.use(settings.httpAdminRoot, RED.httpAdmin);

// Mount node HTTP endpoints at /api
app.use(settings.httpNodeRoot, RED.httpNode);

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

server.listen(settings.uiPort, async () => {
    console.log(`Server listening on port ${settings.uiPort}`);
    await RED.start();
});

Scenario - Programmatic flow deployment

Load and deploy a flow programmatically after startup without using the editor UI.

import RED from 'node-red';
import fs from 'fs-extra';
import http from 'http';

const settings = require('./settings.js');
const server = http.createServer();

RED.init(server, settings);

server.listen(1880, async () => {
    await RED.start();

    const flow = JSON.parse(
        await fs.readFile('./my-flow.json', 'utf8')
    );

    // Deploy flows via the runtime API
    await RED.runtime.flows.setFlows({
        flows: flow,
        type: 'full',
        user: { username: 'admin', permissions: '*' }
    });

    console.log('Flow deployed successfully');
});

Scenario - Register a custom node type before startup

Package a custom node and register it so it appears in the editor palette.

import RED from 'node-red';
import http from 'http';

const settings = require('./settings.js');
const server = http.createServer();

RED.init(server, settings);

// Register custom node type
RED.nodes.registerType('my-sensor', function (this: any, config: any) {
    RED.nodes.createNode(this, config);
    const interval = setInterval(() => {
        this.send({ payload: Math.random(), topic: 'sensor' });
    }, config.interval || 5000);
    this.on('close', () => clearInterval(interval));
});

server.listen(1880, async () => {
    await RED.start();
    console.log('Node-RED started with custom node');
});

File walkthrough

• node_modules/node-red/ - Root package; exports init, start, stop, httpAdmin, httpNode, and delegates to all sub-packages.
• node_modules/@node-red/editor-api/ - Express router factory that mounts all admin and editor HTTP endpoints; requires a runtime instance.
• node_modules/@node-red/editor-api/lib/admin/ - Individual Express route handlers for flows, nodes, settings, context values, diagnostics, and plugins.
• node_modules/@node-red/editor-api/lib/auth/ - Passport.js strategy setup, bearer token validation, user credential lookup, and permission enforcement middleware.
• node_modules/@node-red/editor-api/lib/editor/ - WebSocket comms handler, credential encryption routes, library storage, locale serving, project API, SSH key management, theme config, and static UI serving.
• node_modules/@node-red/editor-client/ - Contains the compiled browser bundle (HTML/JS/CSS) for the flow editor; served as static files by editor-api.
• node_modules/@node-red/editor-client/locales/ - JSON translation catalogs for all supported UI languages; loaded on demand by the editor.
• node_modules/@node-red/nodes/ - Ships all built-in node definitions (function, inject, debug, http request/in, file, switch, change, etc.).
• node_modules/@node-red/registry/ - Manages discovery, loading, and unloading of external node npm packages at runtime.
• node_modules/@node-red/runtime/ - The execution engine: parses flow JSON, instantiates nodes, routes messages, handles context storage.
• node_modules/@node-red/util/ - Cross-package shared code: structured logger, i18next wrapper, typed hook system, misc helpers.

Common pitfalls and fixes

• Missing userDir at startup: Node-RED will crash if userDir does not exist. Fix: add fs-extra's ensureDirSync(settings.userDir) before calling RED.init().
• credentialSecret not set: Without it credentials are stored unencrypted and a warning is logged on every start. Fix: always set a stable random string in env and reference it in settings.
• Port conflict with existing Express server: Calling server.listen() before RED.init() causes the editor's WebSocket setup to fail. Fix: always call RED.init(server, settings) before server.listen().
• Node.js version below 18: user@example.com uses structuredClone, fetch, and other Node 18+ globals. Fix: enforce "engines": { "node": ">=18" } in your package.json.
• ESM/CJS interop with TypeScript: Node-RED packages are CJS. If your project uses "type": "module", imports will fail. Fix: use createRequire or set "module": "commonjs" in tsconfig.json.
• Credential file mismatch after secret rotation: Changing credentialSecret makes all stored credentials unreadable. Fix: decrypt with old secret first using flows:decrypt approach, or delete flows_cred.json and re-enter credentials.

Vibe-coding prompt template

I have a local copy of the Node-RED core packages (node-red@4.1.8) under
`source/node_modules/` in my project. I also have USAGE.md which documents
the public API and setup steps.

My project is a Node.js/TypeScript Express application. I need you to:

1. Read USAGE.md carefully to understand the real exports and file layout
   under source/.
2. Install all required dependencies listed in the "Required dependencies"
   section of USAGE.md.
3. Create a settings.js file with sensible defaults for my project, reading
   sensitive values (credentialSecret, port) from environment variables.
4. Wire node-red into my existing Express app (app.ts / server.ts) using
   RED.init(), RED.httpAdmin, and RED.httpNode as shown in USAGE.md.
5. Ensure userDir is created before RED.init() is called.
6. Register the custom node type I will describe, using RED.nodes.registerType,
   before calling RED.start().
7. Add a /health endpoint that returns Node-RED version via RED.version().
8. Show me the final app.ts, settings.js, and package.json changes as separate
   fenced code blocks.

Do not invent any API symbols. Use only what is documented in USAGE.md and
visible in source/. Ask me before making assumptions about my existing
project structure.

License and credit

Node-RED is licensed under the Apache License 2.0. Copyright OpenJS Foundation and contributors. See source/node_modules/node-red/LICENSE or the full text at https://www.apache.org/licenses/LICENSE-2.0.

Upstream package: node-red on npm | GitHub repository | Documentation.

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.

ToolJet Open-Source Low-Code App Builder

Automation, Utilities & Developer Tools

Free