/n8n-code-javascript

name: n8n-code-javascript
description: Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with this.helpers / the $helpers global, working with dates using DateTime, troubleshooting Code node errors, choosing between Code node modes, or doing any custom data transformation in n8n. Always use this skill when a workflow needs a Code node — whether for data aggregation, filtering, API calls, format conversion, batch processing logic, or any custom JavaScript. Covers SplitInBatches loop patterns, cross-iteration data, pairedItem, and real-world production patterns. Also use when asked why a Code node or workflow is slow, which execution mode is faster, or how to cut per-item overhead on large datasets. EXCEPTION — for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode, a tool attached to an AI Agent), use the n8n-code-tool skill instead; it has a different runtime contract.

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. **Return `[{json: {...}}]`** — the canonical, mode-portable form. In *Run Once for All Items* mode n8n also auto-wraps a bare `return {…}` object, so that runs too; what genuinely fails is returning a primitive (string/number) or `null`. 4. **CRITICAL**: Webhook data is under `$json.body` (not `$json` directly) 5. **Built-ins available**: `this.helpers.httpRequest()` (no auth — the bare `$helpers` global is **undefined** in the task-runner sandbox, so `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`), DateTime (Luxon), $jmespath(). **Not available**: `this.helpers.httpRequestWithAuthentication` (deny-listed), $env (when N8N_BLOCK_ENV_ACCESS_IN_NODE=true), require() (unless allowlisted). For anything beyond a trivial unauthenticated GET (auth, pagination, retries), prefer the **HTTP Request node** and keep Code nodes for pure logic. 6. **Instance-allowlisted libraries**: Self-hosted instances can allowlist modules via `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` and `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` (legacy: `NODE_FUNCTION_ALLOW_BUILTIN` / `NODE_FUNCTION_ALLOW_EXTERNAL`). If the user says their instance allows specific modules (e.g. `axios`, `lodash`, `crypto`), use them via `require()` — don't refuse. If unsure, ask or default to built-ins only. 7. **Wrong skill?** If you're writing code for a **Custom Code Tool** attached to an AI Agent (`@n8n/n8n-nodes-langchain.toolCode`), stop — that node has a different contract (input via `query`, must return a string, no `$input`/`$helpers`). Use the **n8n-code-tool** skill.

---

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)

Why "All Items" is faster — the per-item boundary

Mode choice is the single biggest performance lever in a Code node. Each *per-item* execution context costs a setup tax (measured on n8n 2.x, small records):

| What runs per item | Approx. cost | |---|---| | Code **All Items** (one run for the whole set) | ~0.02 ms/item | | Expression in any node (IF / Set / etc.) | ~0.2 ms/item | | Code **Each Item** (a full sandbox per item) | ~0.6 ms/item — ~25–30× All Items |

So `Run Once for Each Item` over 10k items is ~6 s of pure overhead vs ~0.2 s in `Run Once for All Items`. Use Each Item only when an item genuinely needs isolating (independent error handling, or a per-item API call you can't batch); otherwise loop *inside* one All Items node. Expression complexity itself is essentially free (~90% of the cost is the per-item context, not your code) and every node→node hop re-copies all items — so reduce the *number* o