JavaScript Code Node

Expert guidance for writing JavaScript code in n8n Code nodes.

Quick Start

// Basic template for Code nodes
const items = $input.all();

// Process data
const processed = items.map(item => ({
  json: {
    ...item.json,
    processed: true,
    timestamp: new Date().toISOString()
  }
}));

return processed;

Essential Rules

1. Choose "Run Once for All Items" mode (recommended for most use cases)
2. Access data: $input.all(), $input.first(), or $input.item
3. CRITICAL: Must return [{json: {...}}] format
4. CRITICAL: Webhook data is under $json.body (not $json directly)
5. Built-ins available: $helpers.httpRequest(), DateTime (Luxon), $jmespath()

Mode Selection Guide

The Code node offers two execution modes. Choose based on your use case:

Run Once for All Items (Recommended - Default)

Use this mode for: 95% of use cases

• How it works: Code executes once regardless of input count
• Data access: $input.all() or items array
• Best for: Aggregation, filtering, batch processing, transformations, API calls with all data
• Performance: Faster for multiple items (single execution)

// Example: Calculate total from all items
const allItems = $input.all();
const total = allItems.reduce((sum, item) => sum + (item.json.amount || 0), 0);

return [{
  json: {
    total,
    count: allItems.length,
    average: total / allItems.length
  }
}];

When to use:

• ✅ Comparing items across the dataset
• ✅ Calculating totals, averages, or statistics
• ✅ Sorting or ranking items
• ✅ Deduplication
• ✅ Building aggregated reports
• ✅ Combining data from multiple items

Run Once for Each Item

Use this mode for: Specialized cases only

• How it works: Code executes separately for each input item
• Data access: $input.item or $item
• Best for: Item-specific logic, independent operations, per-item validation
• Performance: Slower for large datasets (multiple executions)

// Example: Add processing timestamp to each item
const item = $input.item;

return [{
  json: {
    ...item.json,
    processed: true,
    processedAt: new Date().toISOString()
  }
}];

When to use:

• ✅ Each item needs independent API call
• ✅ Per-item validation with different error handling
• ✅ Item-specific transformations based on item properties
• ✅ When items must be processed separately for business logic

Decision Shortcut:

• Need to look at multiple items? → Use "All Items" mode
• Each item completely independent? → Use "Each Item" mode
• Not sure? → Use "All Items" mode (you can always loop inside)

Data Access Patterns

Pattern 1: $input.all() - Most Common

Use when: Processing arrays, batch operations, aggregations

// Get all items from previous node
const allItems = $input.all();

// Filter, map, reduce as needed
const valid = allItems.filter(item => item.json.status === 'active');
const mapped = valid.map(item => ({
  json: {
    id: item.json.id,
    name: item.json.name
  }
}));

return mapped;

Pattern 2: $input.first() - Very Common

Use when: Working with single objects, API responses, first-in-first-out

// Get first item only
const firstItem = $input.first();
const data = firstItem.json;

return [{
  json: {
    result: processData(data),
    processedAt: new Date().toISOString()
  }
}];

Pattern 3: $input.item - Each Item Mode Only

Use when: In "Run Once for Each Item" mode

// Current item in loop (Each Item mode only)
const currentItem = $input.item;

return [{
  json: {
    ...currentItem.json,
    itemProcessed: true
  }
}];

Pattern 4: $node - Reference Other Nodes

Use when: Need data from specific nodes in workflow

// Get output from specific node
const webhookData = $node["Webhook"].json;
const httpData = $node["HTTP Request"].json;

return [{
  json: {
    combined: {
      webhook: webhookData,
      api: httpData
    }
  }
}];

See: DATA_ACCESS.md for comprehensive guide

Critical: Webhook Data Structure

MOST COMMON MISTAKE: Webhook data is nested under .body

// ❌ WRONG - Will return undefined
const name = $json.name;
const email = $json.email;

// ✅ CORRECT - Webhook data is under .body
const name = $json.body.name;
const email = $json.body.email;

// Or with $input
const webhookData = $input.first().json.body;
const name = webhookData.name;

Why: Webhook node wraps all request data under body property. This includes POST data, query parameters, and JSON payloads.

See: DATA_ACCESS.md for full webhook structure details

Return Format Requirements

CRITICAL RULE: Always return array of objects with json property

Correct Return Formats

// ✅ Single result
return [{
  json: {
    field1: value1,
    field2: value2
  }
}];

// ✅ Multiple results
how to use n8n-code-javascript
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use n8n-code-javascript on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add n8n-code-javascript
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/czlonkowski/n8n-skills --skill n8n-code-javascriptcopy
The skills CLI fetches n8n-code-javascript from GitHub repository czlonkowski/n8n-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/n8n-code-javascript
Reload or restart Cursor to activate n8n-code-javascript. Access the skill through slash commands (e.g., /n8n-code-javascript) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?