0
# @node-red/nodes
1

2
The @node-red/nodes package provides the complete collection of core nodes for the Node-RED visual programming platform. These nodes serve as fundamental building blocks that developers use to create flows for event-driven applications, IoT automation, data integration, and industrial systems. Each node type provides specific functionality and can be connected together to build complex workflows without traditional coding.
3

4
## Package Information
5

6
- **Package Name**: @node-red/nodes
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @node-red/nodes`
10

11
## Core Imports
12

13
**Important**: This package is designed to be loaded by the Node-RED runtime, not imported directly by applications. The main entry point exports `false`:
14

15
```javascript
16
// This package is not intended for direct import
17
// const nodes = require('@node-red/nodes'); // exports false
18

19
// Instead, nodes are registered with Node-RED runtime:
20
module.exports = function(RED) {
21
    // Node definitions register themselves with RED
22
    RED.nodes.registerType("node-type", NodeConstructor);
23
};
24
```
25

26
## Basic Usage
27

28
@node-red/nodes is consumed by the Node-RED runtime during startup. Users interact with these nodes through the Node-RED visual editor by dragging nodes from the palette and connecting them to create flows:
29

30
```javascript
31
// Example of how Node-RED runtime loads this package
32
// (This happens automatically when Node-RED starts)
33

34
// Each node follows this registration pattern:
35
module.exports = function(RED) {
36
    function InjectNode(config) {
37
        RED.nodes.createNode(this, config);
38
        
39
        this.on("input", function(msg, send, done) {
40
            // Process incoming messages
41
            send(msg); // Forward to next node
42
            done();    // Signal completion
43
        });
44
    }
45
    
46
    RED.nodes.registerType("inject", InjectNode);
47
};
48
```
49

50
## Architecture
51

52
The @node-red/nodes package is organized into six core categories:
53

54
- **Common Nodes**: Basic flow control and debugging utilities
55
- **Function Nodes**: Data processing, transformation, and custom logic execution
56
- **Network Nodes**: Communication protocols (HTTP, MQTT, WebSocket, TCP/UDP)
57
- **Parser Nodes**: Data format conversion (JSON, XML, CSV, HTML, YAML)
58
- **Sequence Nodes**: Message flow control and batching operations
59
- **Storage Nodes**: File system operations and monitoring
60

61
Each node is implemented as a factory function that receives the Node-RED runtime (`RED`) and registers itself with a specific node type name. The runtime manages node lifecycle, message routing, and configuration.
62

63
## Capabilities
64

65
### Common Flow Control
66

67
Essential nodes for flow control, debugging, and basic automation including manual triggers, error handling, and debugging output.
68

69
```javascript { .api }
70
// Inject node - manual/scheduled triggers
71
function InjectNode(config) { /* ... */ }
72

73
// Debug node - output messages for debugging  
74
function DebugNode(config) { /* ... */ }
75

76
// Catch node - error handling
77
function CatchNode(config) { /* ... */ }
78
```
79

80
[Common Nodes](./common-nodes.md)
81

82
### Function and Logic
83

84
Data processing capabilities including custom JavaScript execution, conditional routing, data transformation, and templating.
85

86
```javascript { .api }
87
// Function node - custom JavaScript execution
88
function FunctionNode(config) { /* ... */ }
89

90
// Switch node - conditional message routing
91
function SwitchNode(config) { /* ... */ }
92

93
// Change node - modify message properties
94
function ChangeNode(config) { /* ... */ }
95
```
96

97
[Function Nodes](./function-nodes.md)
98

99
### Network Communication
100

101
Comprehensive networking capabilities supporting HTTP servers and clients, MQTT messaging, WebSocket connections, and TCP/UDP communication.
102

103
```javascript { .api }
104
// HTTP endpoints
105
function HTTPInNode(config) { /* ... */ }
106
function HTTPRequestNode(config) { /* ... */ }
107

108
// MQTT messaging  
109
function MqttInNode(config) { /* ... */ }
110
function MqttOutNode(config) { /* ... */ }
111

112
// WebSocket connections
113
function WebSocketInNode(config) { /* ... */ }
114
```
115

116
[Network Nodes](./network-nodes.md)
117

118
### Data Parsing
119

120
Data format conversion utilities for working with JSON, XML, CSV, HTML, and YAML formats with parsing and generation capabilities.
121

122
```javascript { .api }
123
// JSON parse/stringify
124
function JSONNode(config) { /* ... */ }
125

126
// XML parse/generate
127
function XMLNode(config) { /* ... */ }
128

129
// CSV parse/generate  
130
function CSVNode(config) { /* ... */ }
131
```
132

133
[Parser Nodes](./parser-nodes.md)
134

135
### Sequence Control
136

137
Message sequence manipulation including splitting, joining, sorting, and batching operations for handling arrays and message streams.
138

139
```javascript { .api }
140
// Split messages into sequences
141
function SplitNode(config) { /* ... */ }
142

143
// Join sequences back together
144
function JoinNode(config) { /* ... */ }
145

146
// Sort message sequences
147
function SortNode(config) { /* ... */ }
148
```
149

150
[Sequence Nodes](./sequence-nodes.md)
151

152
### File Operations
153

154
File system interaction capabilities for reading, writing, and monitoring files and directories.
155

156
```javascript { .api }
157
// File read/write operations
158
function FileNode(config) { /* ... */ }
159
function FileInNode(config) { /* ... */ }
160

161
// File system monitoring
162
function WatchNode(config) { /* ... */ }
163
```
164

165
[Storage Nodes](./storage-nodes.md)
166

167
## HTTP Administration Endpoints
168

169
Several nodes expose HTTP endpoints for remote control and monitoring:
170

171
```javascript { .api }
172
// Debug control endpoints
173
POST /debug/:state           // Global debug control
174
POST /debug/:id/:state       // Individual node control
175
GET  /debug/view/view.html   // Debug viewer interface
176

177
// Inject control endpoint  
178
POST /inject/:id             // Trigger inject nodes remotely
179

180
// UDP port information
181
GET  /udp-ports/:id          // Get UDP port details
182
GET  /debug/view/*           // Debug viewer static resources
183
```
184

185
## Configuration Node Types
186

187
Configuration nodes provide shared settings for other nodes:
188

189
```javascript { .api }
190
// MQTT broker configuration
191
function MqttBrokerNode(config) { /* ... */ }
192

193
// TLS/SSL configuration
194
function TLSConfigNode(config) { /* ... */ }
195

196
// HTTP proxy configuration  
197
function HttpProxyNode(config) { /* ... */ }
198

199
// WebSocket server configuration
200
function WebSocketListenerNode(config) { /* ... */ }
201

202
// WebSocket client configuration
203
function WebSocketClientNode(config) { /* ... */ }
204
```
205

206
## Types
207

208
```javascript { .api }
209
// Standard Node-RED message structure
210
interface NodeMessage {
211
    payload: any;           // Main message content
212
    topic?: string;         // Message topic/subject
213
    _msgid: string;         // Unique message identifier
214
    [key: string]: any;     // Additional properties
215
}
216

217
// Node configuration base
218
interface NodeConfig {
219
    id: string;             // Unique node ID
220
    type: string;           // Node type name
221
    name?: string;          // Optional display name
222
    [key: string]: any;     // Node-specific configuration
223
}
224

225
// Node constructor function signature  
226
type NodeRegistrationFunction = (RED: NodeREDRuntime) => void;
227

228
// Node instance methods
229
interface NodeInstance {
230
    on(event: string, handler: Function): void;
231
    send(msgs: NodeMessage | NodeMessage[]): void;
232
    error(error: string | Error, msg?: NodeMessage): void;
233
    warn(warning: string): void;
234
    log(message: string): void;
235
}
236
```