0
# Node-RED
1

2
Node-RED is a low-code programming platform for event-driven applications that enables developers to create IoT applications, automation workflows, and data processing pipelines through a visual flow-based editor. It provides both a runtime system for executing flows and a complete development environment with drag-and-drop nodes, visual programming, and extensive extensibility.
3

4
## Package Information
5

6
- **Package Name**: node-red
7
- **Package Type**: npm
8
- **Language**: JavaScript/Node.js
9
- **Installation**: `npm install node-red`
10
- **CLI Installation**: `npm install -g node-red`
11

12
## Core Imports
13

14
```javascript
15
const RED = require("node-red");
16
```
17

18
ES Modules:
19
```javascript
20
import RED from "node-red";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const RED = require("node-red");
27
const express = require("express");
28
const http = require("http");
29

30
// Create Express app and HTTP server
31
const app = express();
32
const server = http.createServer(app);
33

34
// Initialize Node-RED
35
RED.init(server, {
36
    functionGlobalContext: {},
37
    userDir: "./node-red-data",
38
});
39

40
// Start Node-RED
41
RED.start().then(() => {
42
    console.log("Node-RED started");
43
    
44
    // Serve the editor on /red
45
    app.use("/red", RED.httpAdmin);
46
    
47
    // Serve HTTP nodes on /api
48
    app.use("/api", RED.httpNode);
49
    
50
    server.listen(3000, () => {
51
        console.log("Server running on port 3000");
52
        console.log("Editor available at http://localhost:3000/red");
53
    });
54
});
55
```
56

57
## Architecture
58

59
Node-RED is built around several key components:
60

61
- **Main Module**: Core application entry point with lifecycle management (`init`, `start`, `stop`)
62
- **Runtime System**: Flow execution engine with node management and messaging system
63
- **Editor API**: RESTful API and WebSocket interface for the browser-based flow editor
64
- **HTTP Services**: Express applications for serving the editor and HTTP-based nodes
65
- **Node Registry**: Dynamic loading and management of node types and modules
66
- **Context System**: Persistent data storage across nodes, flows, and global scopes
67
- **Function Sandbox**: Secure JavaScript execution environment for Function nodes
68

69
## Capabilities
70

71
### Application Lifecycle
72

73
Core application initialization and control for embedding Node-RED in other applications.
74

75
```javascript { .api }
76
/**
77
 * Initialize the Node-RED application
78
 * @param httpServer - HTTP server instance (optional)
79
 * @param userSettings - Configuration settings object
80
 */
81
function init(httpServer?: http.Server, userSettings: UserSettings): void;
82

83
/**
84
 * Start the Node-RED runtime and editor
85
 * @returns Promise that resolves when startup is complete
86
 */
87
function start(): Promise<void>;
88

89
/**
90
 * Stop the Node-RED runtime and editor
91
 * @returns Promise that resolves when shutdown is complete
92
 */
93
function stop(): Promise<void>;
94
```
95

96
[Application Management](./application.md)
97

98
### Runtime API
99

100
Programmatic access to flow management, node operations, and runtime control for administrative applications.
101

102
```javascript { .api }
103
/**
104
 * Runtime API for flow and node management
105
 */
106
interface RuntimeAPI {
107
    flows: FlowsAPI;
108
    nodes: NodesAPI;
109
    settings: SettingsAPI;
110
    library: LibraryAPI;
111
    context: ContextAPI;
112
    projects: ProjectsAPI;
113
    diagnostics: DiagnosticsAPI;
114
    plugins: PluginsAPI;
115
}
116

117
/**
118
 * Get current flow configuration
119
 * @param opts - Request options
120
 * @returns Promise resolving to flow configuration
121
 */
122
flows.getFlows(opts: RequestOptions): Promise<FlowConfig[]>;
123

124
/**
125
 * Set flow configuration
126
 * @param opts - Request options with flow data
127
 * @returns Promise resolving to deployment result
128
 */
129
flows.setFlows(opts: RequestOptions & { flows: FlowConfig[] }): Promise<DeploymentResult>;
130
```
131

132
[Runtime Operations](./runtime.md)
133

134
### Utility Functions
135

136
General-purpose utilities for message handling, logging, and Node-RED development.
137

138
```javascript { .api }
139
/**
140
 * Logging system
141
 */
142
interface LoggingAPI {
143
    info(msg: any): void;
144
    warn(msg: any): void;
145
    error(msg: any): void;
146
    debug(msg: any): void;
147
    trace(msg: any): void;
148
    audit(event: AuditEvent, req?: http.IncomingMessage): void;
149
}
150

151
/**
152
 * General utilities for message manipulation
153
 */
154
interface UtilityAPI {
155
    generateId(length?: number): string;
156
    cloneMessage(msg: NodeMessage): NodeMessage;
157
    getMessageProperty(msg: NodeMessage, prop: string): any;
158
    setMessageProperty(msg: NodeMessage, prop: string, value: any, createMissing?: boolean): boolean;
159
    evaluateNodeProperty(value: any, type: string, node: NodeObject, msg: NodeMessage): any;
160
}
161
```
162

163
[Utilities](./utilities.md)
164

165
### Function Node Development
166

167
JavaScript execution environment and APIs available within Function nodes for custom logic implementation.
168

169
```javascript { .api }
170
/**
171
 * Available in Function node context
172
 */
173
interface FunctionNodeContext {
174
    msg: NodeMessage;
175
    node: NodeInstance;
176
    context: ContextStore;
177
    flow: ContextStore;
178
    global: ContextStore;
179
    env: EnvironmentVariables;
180
    RED: NodeREDUtilities;
181
}
182

183
/**
184
 * Node instance methods available in Function nodes
185
 */
186
interface NodeInstance {
187
    send(msg: NodeMessage | NodeMessage[], clone?: boolean): void;
188
    error(err: string | Error, msg?: NodeMessage): void;
189
    warn(warning: string | object): void;
190
    log(info: string | object): void;
191
    status(status: NodeStatus | string | boolean | number): void;
192
}
193
```
194

195
[Function Nodes](./function-nodes.md)
196

197
### Node Development
198

199
APIs for creating custom node types and extending Node-RED functionality.
200

201
```javascript { .api }
202
/**
203
 * Node registration function (available in node modules)
204
 */
205
interface NodeAPI {
206
    registerType(type: string, constructor: NodeConstructor): void;
207
    getNode(id: string): NodeInstance | null;
208
    createNode(node: NodeInstance, config: NodeConfig): void;
209
}
210

211
/**
212
 * Node constructor interface
213
 */
214
interface NodeConstructor {
215
    (this: NodeInstance, config: NodeConfig): void;
216
}
217
```
218

219
[Node Development](./node-development.md)
220

221
### HTTP Services
222

223
Express applications for building web interfaces and HTTP endpoints within Node-RED applications.
224

225
```javascript { .api }
226
/**
227
 * Express application for editor interface
228
 */
229
const httpAdmin: express.Application;
230

231
/**
232
 * Express application for HTTP nodes
233
 */
234
const httpNode: express.Application;
235

236
/**
237
 * HTTP server instance
238
 */
239
const server: http.Server;
240
```
241

242
[HTTP Integration](./http-services.md)
243

244
### Command Line Interface
245

246
Command-line tools for running Node-RED server, managing node modules, and administrative operations.
247

248
```bash { .api }
249
# Start Node-RED server
250
node-red [options]
251

252
# Administrative commands
253
node-red admin <command> [options]
254

255
# Common options
256
-p, --port PORT        # Port to listen on (default: 1880)
257
-s, --settings FILE    # Settings file to use
258
-u, --userDir DIR      # User directory (default: ~/.node-red)
259
--safe                 # Enable safe mode (no flows loaded)
260
-v, --verbose          # Enable verbose output
261
```
262

263
[Command Line Interface](./cli.md)
264

265
## Types
266

267
```javascript { .api }
268
interface UserSettings {
269
    uiPort?: number;
270
    uiHost?: string;
271
    httpAdminRoot?: string;
272
    httpNodeRoot?: string;
273
    userDir?: string;
274
    flowFile?: string;
275
    credentialSecret?: string;
276
    httpNodeCors?: object;
277
    logging?: object;
278
    contextStorage?: object;
279
    functionGlobalContext?: object;
280
    exportGlobalContextKeys?: boolean;
281
    externalModules?: object;
282
}
283

284
interface NodeMessage {
285
    _msgid: string;
286
    topic?: string;
287
    payload: any;
288
    [key: string]: any;
289
}
290

291
interface FlowConfig {
292
    id: string;
293
    type: string;
294
    name?: string;
295
    disabled?: boolean;
296
    info?: string;
297
    [key: string]: any;
298
}
299

300
interface RequestOptions {
301
    user?: UserObject;
302
    req?: http.IncomingMessage;
303
}
304

305
interface NodeStatus {
306
    fill?: 'red' | 'green' | 'yellow' | 'blue' | 'grey';
307
    shape?: 'ring' | 'dot';
308
    text?: string;
309
}
310
```