N8n Code Javascript

JavaScript Code Node

Expert guidance for writing JavaScript code in n8n Code nodes. JavaScript is recommended for 95% of n8n Code use cases — full $helpers, Luxon DateTime, no library limitations.

When to use

• Writing or reviewing a JavaScript Code node in n8n.
• Using $input / $json / $node syntax.
• Making HTTP requests with $helpers.httpRequest.
• Date/time work with DateTime (Luxon).
• Querying JSON with $jmespath.
• Choosing between Code node modes (All Items vs Each Item).
• Debugging Code node errors (return shape, webhook nesting, undefined fields).

Required input contract

Before writing or reviewing a JavaScript Code node, identify:

• Mode — "Run Once for All Items" (default, 95% of cases) vs "Run Once for Each Item".
• Upstream node(s) — which provides the input (webhook, HTTP, manual, prior Code node).
• Required output cardinality — single, list, empty, or filtered.
• External calls — does this node need $helpers.httpRequest?
• Reason for Code node — not solvable by Set / Filter / IF / HTTP Request nodes alone.

n8n JavaScript Code node constraints

These constraints apply to every JavaScript Code node and must always be respected.

1. Return shape: every code path returns an array of objects each with a json key. Single returns wrapped in array. Empty result is return [].
2. Webhook data nests under .body. Use $json.body?.<field> or $input.first().json.body.
3. Optional chaining + nullish coalescing for nullable fields: $json.body?.name ?? "".
4. No {{ }} expression syntax inside the Code node body. Code nodes execute pure JavaScript — use template literals or direct access.
5. $helpers.httpRequest always inside try/catch. Awaitable; throws on failure.
6. DateTime time zones pinned explicitly when crossing zones — never rely on the server default.
7. Do not mutate item.json in place — construct new objects ({ json: { ...item.json, extra: v } }).
8. Do not return $input.all() raw — map first to produce a fresh { json } shape.
9. Credentials live in n8n credential storage, never in source.

Workflow (compact)

1. Mode: All Items (default) vs Each Item.
2. Read: $input.all() / .first() / .item / $node["..."].json.
3. Transform: array methods (map / filter / reduce).
4. Return: [{ json: {...} }, ...] on every code path.
5. Validate: walk the gates (below).

Full workflow + mode examples + return-format matrix: references/javascript-code-workflow.md.

Decision logic

Mode selection

Data access

When to use the Code node vs another node

Minimal critical examples

Quick Start

const items = $input.all();
return items.map(item => ({
  json: {
    ...item.json,
    processed: true,
    timestamp: new Date().toISOString(),
  },
}));

Webhook field access

const name = $json.body?.name ?? "";
return [{ json: { name: name.trim() } }];

HTTP from inside the Code node

try {
  const res = await $helpers.httpRequest({
    method: "GET",
    url: "https://api.example.com/items",
  });
  return res.data.map(it => ({ json: { id: it.id, name: it.name } }));
} catch (err) {
  return [{ json: { ok: false, error: err.message } }];
}

Return-format right/wrong

return [{ json: { id: 1 } }];                            // RIGHT — single
return [{ json: { id: 1 } }, { json: { id: 2 } }];       // RIGHT — multiple
return [];                                               // RIGHT — empty
return { json: { id: 1 } };                              // WRONG — not wrapped
return [{ id: 1 }];                                      // WRONG — missing "json" key
return $input.all();                                     // WRONG — raw input

Worked end-to-end examples (webhook, API fetch + merge, group-by, multi-node combine, regex extract, per-item conditional, date-range filter): references/examples.md.

Validation gates

Before deploying a JavaScript Code node:

• Code is not empty.
• Final return statement exists.
• Return shape is [{ json: {...} }, ...] on every code path.
• Data access uses only $input.all() / $input.first() / $input.item / $node["..."].json.
• No {{ }} expression syntax inside the Code node body.
• ?. and ?? used for nullable fields.
• Webhook data accessed via $json.body?.<field>.
• try/catch wraps every $helpers.httpRequest.
• Mode is "All Items" unless per-item independence is required.
• Output consistent across every branch and exception path.
• DateTime time zones pinned explicitly when crossing zones.

Full top-5 mistakes, best practices, debugging playbook, anti-patterns: references/validation-troubleshooting-and-antipatterns.md.

Output expectations

When delivering a JavaScript Code node:

• Provide the full code block, ready to paste into the Code node.
• State the mode (All Items / Each Item).
• Note any required upstream nodes.
• Flag any branch that returns [] and what that means downstream.
• List required credentials if $helpers.httpRequest is used.

Integration with other skills

• n8n Expression Syntax — expressions use {{ }} in other nodes; Code nodes use JavaScript directly.
• n8n MCP Tools Expert — find Code node via search_nodes({query: "code"}); configure via get_node({nodeType: "nodes-base.code"}); validate via validate_node({nodeType: "nodes-base.code", config: {...}}).
• n8n Node Configuration — mode and language selection are node properties.
• n8n Workflow Patterns — Code nodes in transformation steps; Webhook → Code → API; error handling.
• n8n Validation Expert — interpret validation errors, auto-fix.
• n8n Code Python — when to switch (rare); feature comparison.

Reference map