gh-czlonkowski-n8n-skills/skills/n8n-code-javascript/README.md

n8n Code JavaScript

Expert guidance for writing JavaScript code in n8n Code nodes.

---

Purpose

Teaches how to write effective JavaScript in n8n Code nodes, avoid common errors, and use built-in functions effectively.

---

Activates On

Trigger keywords:

• "javascript code node"
• "write javascript in n8n"
• "code node javascript"
• "$input syntax"
• "$json syntax"
• "$helpers.httpRequest"
• "DateTime luxon"
• "code node error"
• "webhook data code"
• "return format code node"

Common scenarios:

• Writing JavaScript code in Code nodes
• Troubleshooting Code node errors
• Making HTTP requests from code
• Working with dates and times
• Accessing webhook data
• Choosing between All Items and Each Item mode

---

What You'll Learn

Quick Start

• Mode selection (All Items vs Each Item)
• Data access patterns ($input.all(), $input.first(), $input.item)
• Correct return format: [{json: {...}}]
• Webhook data structure (.body nesting)
• Built-in functions overview

Data Access Mastery

• $input.all() - Batch operations (most common)
• $input.first() - Single item operations
• $input.item - Each Item mode processing
• $node - Reference other workflow nodes
• Critical gotcha: Webhook data under .body

Common Patterns (Production-Tested)

1. Multi-source Data Aggregation
2. Regex Filtering & Pattern Matching
3. Markdown Parsing & Structured Extraction
4. JSON Comparison & Validation
5. CRM Data Transformation
6. Release Information Processing
7. Array Transformation with Context
8. Slack Block Kit Formatting
9. Top N Filtering & Ranking
10. String Aggregation & Reporting

Error Prevention

Top 5 errors to avoid:

1. Empty code / missing return (38% of failures)
2. Expression syntax confusion (using {{}} in code)
3. Incorrect return format (missing array wrapper or json property)
4. Unmatched brackets (string escaping issues)
5. Missing null checks (crashes on undefined)

Built-in Functions

• $helpers.httpRequest() - Make HTTP requests
• DateTime (Luxon) - Advanced date/time operations
• $jmespath() - Query JSON structures
• $getWorkflowStaticData() - Persistent storage
• Standard JavaScript globals (Math, JSON, console)
• Available Node.js modules (crypto, Buffer, URL)

---

File Structure

n8n-code-javascript/
├── SKILL.md (500 lines)
│   Overview, quick start, mode selection, best practices
│   - Mode selection guide (All Items vs Each Item)
│   - Data access patterns overview
│   - Return format requirements
│   - Critical webhook gotcha
│   - Error prevention overview
│   - Quick reference checklist
│
├── DATA_ACCESS.md (400 lines)
│   Complete data access patterns
│   - $input.all() - Most common (26% usage)
│   - $input.first() - Very common (25% usage)
│   - $input.item - Each Item mode (19% usage)
│   - $node - Reference other nodes
│   - Webhook data structure (.body nesting)
│   - Choosing the right pattern
│   - Common mistakes to avoid
│
├── COMMON_PATTERNS.md (600 lines)
│   10 production-tested patterns
│   - Pattern 1: Multi-source Aggregation
│   - Pattern 2: Regex Filtering
│   - Pattern 3: Markdown Parsing
│   - Pattern 4: JSON Comparison
│   - Pattern 5: CRM Transformation
│   - Pattern 6: Release Processing
│   - Pattern 7: Array Transformation
│   - Pattern 8: Slack Block Kit
│   - Pattern 9: Top N Filtering
│   - Pattern 10: String Aggregation
│   - Pattern selection guide
│
├── ERROR_PATTERNS.md (450 lines)
│   Top 5 errors with solutions
│   - Error #1: Empty Code / Missing Return (38%)
│   - Error #2: Expression Syntax Confusion (8%)
│   - Error #3: Incorrect Return Wrapper (5%)
│   - Error #4: Unmatched Brackets (6%)
│   - Error #5: Missing Null Checks
│   - Error prevention checklist
│   - Quick error reference
│   - Debugging tips
│
├── BUILTIN_FUNCTIONS.md (450 lines)
│   Complete built-in function reference
│   - $helpers.httpRequest() API reference
│   - DateTime (Luxon) complete guide
│   - $jmespath() JSON querying
│   - $getWorkflowStaticData() persistent storage
│   - Standard JavaScript globals
│   - Available Node.js modules
│   - What's NOT available
│
└── README.md (this file)
    Skill metadata and overview

Total: ~2,400 lines across 6 files

---

Coverage

Mode Selection

• Run Once for All Items - Recommended for 95% of use cases
• Run Once for Each Item - Specialized cases only
• Decision guide and performance implications

Data Access

• Most common patterns with usage statistics
• Webhook data structure (critical .body gotcha)
• Safe access patterns with null checks
• When to use which pattern

Error Prevention

• Top 5 errors covering 62%+ of all failures
• Clear wrong vs right examples
• Error prevention checklist
• Debugging tips and console.log usage

Production Patterns

• 10 patterns from real workflows
• Complete working examples
• Use cases and key techniques
• Pattern selection guide

Built-in Functions

• Complete $helpers.httpRequest() reference
• DateTime/Luxon operations (formatting, parsing, arithmetic)
• $jmespath() for JSON queries
• Persistent storage with $getWorkflowStaticData()
• Standard JavaScript and Node.js modules

---

Critical Gotchas Highlighted

#1: Webhook Data Structure

MOST COMMON MISTAKE: Webhook data is under .body

// ❌ WRONG
const name = $json.name;

// ✅ CORRECT
const name = $json.body.name;

#2: Return Format

CRITICAL: Must return array with json property

// ❌ WRONG
return {json: {result: 'success'}};

// ✅ CORRECT
return [{json: {result: 'success'}}];

#3: Expression Syntax

Don't use {{}} in Code nodes

// ❌ WRONG
const value = "{{ $json.field }}";

// ✅ CORRECT
const value = $json.field;

---

Integration with Other Skills

n8n Expression Syntax

• Distinction: Expressions use {{}} in OTHER nodes
• Code nodes: Use JavaScript directly (no {{}})
• When to use each: Code vs expressions decision guide

n8n MCP Tools Expert

• Find Code node: search_nodes({query: "code"})
• Get configuration: get_node_essentials("nodes-base.code")
• Validate code: validate_node_operation()

n8n Node Configuration

• Mode selection (All Items vs Each Item)
• Language selection (JavaScript vs Python)
• Understanding property dependencies

n8n Workflow Patterns

• Code nodes in transformation step
• Webhook → Code → API pattern
• Error handling in workflows

n8n Validation Expert

• Validate Code node configuration
• Handle validation errors
• Auto-fix common issues

---

When to Use Code Node

Use Code node when:

• ✅ Complex transformations requiring multiple steps
• ✅ Custom calculations or business logic
• ✅ Recursive operations
• ✅ API response parsing with complex structure
• ✅ Multi-step conditionals
• ✅ Data aggregation across items

Consider other nodes when:

• ❌ Simple field mapping → Use Set node
• ❌ Basic filtering → Use Filter node
• ❌ Simple conditionals → Use IF or Switch node
• ❌ HTTP requests only → Use HTTP Request node

Code node excels at: Complex logic that would require chaining many simple nodes

---

Success Metrics

Before this skill:

• Users confused by mode selection
• Frequent return format errors
• Expression syntax mistakes
• Webhook data access failures
• Missing null check crashes

After this skill:

• Clear mode selection guidance
• Understanding of return format
• JavaScript vs expression distinction
• Correct webhook data access
• Safe null-handling patterns
• Production-ready code patterns

---

Quick Reference

Essential Rules

1. Choose "All Items" mode (recommended)
2. Access data: $input.all(), $input.first(), $input.item
3. MUST return: [{json: {...}}] format
4. Webhook data: Under .body property
5. No {{}} syntax: Use JavaScript directly

Most Common Patterns

• Batch processing → $input.all() + map/filter
• Single item → $input.first()
• Aggregation → reduce()
• HTTP requests → $helpers.httpRequest()
• Date handling → DateTime (Luxon)

Error Prevention

• Always return data
• Check for null/undefined
• Use try-catch for risky operations
• Test with empty input
• Use console.log() for debugging

---

Related Documentation

• n8n Code Node Guide: https://docs.n8n.io/code/code-node/
• Built-in Methods Reference: https://docs.n8n.io/code-examples/methods-variables-reference/
• Luxon Documentation: https://moment.github.io/luxon/

---

Evaluations

5 test scenarios covering:

1. Webhook body gotcha (most common mistake)
2. Return format error (missing array wrapper)
3. HTTP request with $helpers.httpRequest()
4. Aggregation pattern with $input.all()
5. Expression syntax confusion (using {{}})

Each evaluation tests skill activation, correct guidance, and reference to appropriate documentation files.

---

Version History

• v1.0 (2025-01-20): Initial implementation
  • SKILL.md with comprehensive overview
  • DATA_ACCESS.md covering all access patterns
  • COMMON_PATTERNS.md with 10 production patterns
  • ERROR_PATTERNS.md covering top 5 errors
  • BUILTIN_FUNCTIONS.md complete reference
  • 5 evaluation scenarios

---

Author

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Part of the n8n-skills collection.