Node-RED Flow Development

This skill provides comprehensive support for Node-RED development, including flow creation, modification, validation, and deployment through the Admin API.

When to Use This Skill

Use this skill when:

Creating or modifying Node-RED flows (flows.json files)
Building MQTT, HTTP API, or data pipeline integrations
Debugging or validating flow configurations
Working with function nodes and context storage
Deploying flows via the Node-RED Admin API
Converting requirements into Node-RED flow implementations

Available Resources

Scripts (scripts/)

Execute these Python scripts for common Node-RED operations:

generate_uuid.py - Generate valid Node-RED node IDs
```
python scripts/generate_uuid.py [count]
```
validate_flow.py - Validate flow JSON structure and wire connections
```
python scripts/validate_flow.py <flow.json>
```

wire_nodes.py - Connect nodes programmatically

python scripts/wire_nodes.py <flow.json> <source_id> <target_id> [output_port]

create_flow_template.py - Generate boilerplate flows

python scripts/create_flow_template.py <mqtt|http-api|data-pipeline|error-handler> [output.json]

References (references/)

Consult these detailed references as needed:

node_schemas.md - Complete schemas for all Node-RED node types
api_reference.md - Node-RED Admin API documentation with examples
function_snippets.md - Reusable function node code patterns

Assets (assets/)

Use these templates and boilerplate files:

templates/mqtt_flow.json - Complete MQTT pub/sub flow with error handling
templates/http_api_flow.json - REST API with CRUD operations and authentication
boilerplate/function_async.js - Async function node patterns
boilerplate/function_context.js - Context storage examples

Core Workflow

Creating a New Flow

Determine the flow type needed (MQTT, HTTP API, data processing, etc.)
Generate a template using scripts/create_flow_template.py
Modify the template to match requirements
Validate the flow using scripts/validate_flow.py
Deploy via Admin API or save as flows.json

Modifying Existing Flows

Read and parse the flows.json file
Identify nodes by type and ID
Make modifications while preserving:
- Wire connections (arrays of node IDs)
- Tab references (z property)
- Node coordinates (x, y)
Validate changes before saving
Use scripts/wire_nodes.py to connect nodes if needed

Working with Function Nodes

For function nodes, reference:

assets/boilerplate/function_async.js for async operations
assets/boilerplate/function_context.js for context storage
references/function_snippets.md for specific patterns

Available objects in function nodes:

msg - Message object
node - Node API (send, done, error, warn, log, status)
context - Node-scoped storage
flow - Flow-scoped storage
global - Global storage
RED - Runtime API
env - Environment variables

Deploying Flows

To deploy flows via the Admin API:

Retrieve current configuration:
```
GET /flows
```
Modify the configuration as needed

Deploy with appropriate deployment type:

POST /flows
Headers: Node-RED-Deployment-Type: full|nodes|flows|reload

Verify deployment success

Common Patterns

Message Flow Structure

Every Node-RED message follows this pattern:

Primary data in msg.payload
Topic/category in msg.topic
Unique ID in msg._msgid
Additional properties as needed

Error Handling

Implement error handling using:

Try-catch blocks in function nodes
Catch nodes to intercept errors
Status nodes to monitor node states
Dedicated error output wires

Environment Variables

Use environment variables for configuration:

In node properties: $(ENV_VAR_NAME)
In function nodes: env.get("ENV_VAR_NAME")
Via Docker: -e KEY=value

Context Storage Levels

Choose appropriate context level:

Node context: Local to single node
Flow context: Shared within flow/tab
Global context: System-wide sharing
Persistent: Survives restarts (configure in settings.js)

Validation Checklist

Before deploying flows, verify:

JSON syntax is valid
All wire connections reference existing node IDs
Tab references (z property) are correct
Function node JavaScript is syntactically valid
Required configuration nodes exist (MQTT brokers, etc.)
Environment variables are properly referenced
Error handling is implemented

Quick Commands

Generate five Node-RED UUIDs:

python scripts/generate_uuid.py 5

Create an MQTT flow template:

python scripts/create_flow_template.py mqtt my-mqtt-flow.json

Validate a flow file:

python scripts/validate_flow.py flows.json

Wire two nodes together:

python scripts/wire_nodes.py flows.json inject-node-id debug-node-id

Node-RED Configuration

Default File Locations

Flows: ~/.node-red/flows_<hostname>.json
Settings: ~/.node-red/settings.js
Custom nodes: ~/.node-red/node_modules/

Running Node-RED

Normal mode: node-red
Safe mode (no flow execution): node-red --safe
Custom flow file: node-red myflows.json

Best Practices

Use appropriate node types: Prefer change nodes over function nodes for simple transformations
Implement error handling: Always include catch nodes for critical paths
Document flows: Use comment nodes and node descriptions
Organize with tabs: Separate flows by logical function or system
Version control: Store flows.json in git with meaningful commit messages
Test incrementally: Deploy and test small changes frequently
Monitor performance: Use status nodes and debug output wisely

Troubleshooting

For common issues:

Invalid JSON: Use scripts/validate_flow.py to find syntax errors
Broken wires: Check that all wired node IDs exist
Missing configurations: Ensure broker/server configs are included
Function errors: Test JavaScript in isolation first
API deployment fails: Verify authentication and check revision conflicts

Additional Resources

For detailed specifications and examples:

Consult references/node_schemas.md for node property details
Review references/api_reference.md for API operations
Use references/function_snippets.md for tested code patterns
Copy templates from assets/templates/ as starting points

node-red

Safety Notice

Copy this and send it to your AI assistant to learn