n8n-code-javascript

JavaScript コードノード

n8n のコードノードで JavaScript コードを書くための専門的なガイダンスです。

---

コードノードを書く前に

新しいコードノードは、まず次の条件を満たす必要があります。

1. その作業に対応するネイティブノードはありますか？ using-n8n-mcp-skills の作業とノードの対応表を確認してください。Filter、IF / Switch、 Summarize、Aggregate、Split Out、Merge、Compare Datasets、Remove Duplicates、Sort + Limit、Date & Time、XML / HTML / Extract From File / Convert To File、HTTP Request（ページネーション、バッチ処理）、Crypto で、コードノードを使いたくなる作業の大半に対応できます。 各ノードの設定は n8n-node-configuration → NATIVE_NODES.md にあります。
2. そのノード内の短い式で対応できますか？ 関数本体を使わない単一の式です。ヘルパーメソッド（.pluck()、 .sum()、.unique()、$ifEmpty()、.diffTo()）については、n8n-expression-syntax と、n8n-mcp 2.97.0 以降の tools_documentation({topic: "expression_helpers"}) を参照してください。{{ }} 内に複数の文を書くとコードに該当するため、Edit Fields のフィールドではなく、こちらを使います。
3. 対象の作業は、限定リストに含まれていますか？ ノードでは表現できないループや再帰、実行をまたいで状態を保持する処理 （$getWorkflowStaticData）、どのノードでも処理できない解析、許可リストに登録されたライブラリの使用、全アイテムを対象とする負荷の高い処理（数千件のアイテム。明記または計測済み）、あるいはデータの形を整えるだけの連結ノードを 4 個以上置き換える、短いコードノード（約 15 行）。

条件を満たす場合は、コードノードを作成し、次の読者（およびレビュー用フック）が理由を把握できるよう、注記を付けてください。

{ "name": "Flatten category tree", "type": "n8n-nodes-base.code", "notes": "Why Code: Split Out considered — the tree has arbitrary depth (recursion)", "notesInFlow": true }

既存のコードノードの編集やデバッグには、この確認は不要です。ただし、ノードがネイティブノードで行える作業をしている場合は、その旨を伝え、ネイティブノードへの置き換えを提案してください。

---

クイックスタート

// 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;

必須ルール

1. 「Run Once for All Items」モードを選択します（ほとんどの用途で推奨）。
2. データにアクセスします：$input.all()、$input.first()、または $input.item
3. [{json: {...}}] を返します — これはモード間で移植可能な標準形式です。Run Once for All Items モードでは、n8n は単独の return {…} オブジェクトも自動的にラップするため、その形式も動作します。実際に失敗するのは、プリミティブ（文字列／数値）または null を返した場合です。
4. 重要：Webhook データは $json 直下ではなく、$json.body にあります。
5. 利用できる組み込み機能：this.helpers.httpRequest()（認証なし — タスクランナーのサンドボックスでは、単独の $helpers グローバルは undefined のため、$helpers.httpRequest() は ReferenceError: $helpers is not defined をスローします）、DateTime（Luxon）、$jmespath()。利用できない機能：this.helpers.httpRequestWithAuthentication（拒否リスト入り）、$env（N8N_BLOCK_ENV_ACCESS_IN_NODE=true の場合）、require()（許可リストに登録されていない場合）。認証、ページネーション、再試行など、単純な認証なし GET を超える処理には、HTTP Request ノードを優先し、コードノードは純粋なロジックに使用してください。
6. インスタンスで許可リストに登録されたライブラリ：セルフホスト型インスタンスでは、N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES および N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES（旧設定：NODE_FUNCTION_ALLOW_BUILTIN / NODE_FUNCTION_ALLOW_EXTERNAL）を使ってモジュールを許可リストに登録できます。ユーザーがインスタンスで特定のモジュール（例：axios、lodash、crypto）を許可していると伝えた場合は、require() 経由で使用してください。拒否しないでください。不明な場合は確認するか、組み込み機能のみを使うのが既定です。
7. スキルが違いますか？ AI Agent に接続された Custom Code Tool（@n8n/n8n-nodes-langchain.toolCode）向けのコードを書く場合は、そこで作業を中止してください。このノードの仕様は異なります（query 経由で入力を受け取り、文字列を返す必要があり、$input / $helpers はありません）。n8n-code-tool スキルを使用してください。

---

モード選択ガイド

コードノードには、2 つの実行モードがあります。用途に応じて選択してください。

すべてのアイテムを一度に実行（推奨・デフォルト）

このモードの用途： ほとんどのユースケース（95％）

• 仕組み：入力数にかかわらず、コードを一度だけ実行します
• データへのアクセス：$input.all() または items 配列
• 最適な用途：すべてのアイテムを一度に処理する必要があり、上記の条件を満たすロジック
• パフォーマンス：複数のアイテムでは高速です（実行は一度だけ）

// Example: running balance — each item depends on the ones before it,
// which no native node expresses (Summarize gives one total per group, not a running one)
let balance = 0;
return $input.all().map(item => {
  balance += item.json.amount || 0;
  return { json: { ...item.json, balance } };
});

使用する場合：

• ✅ 各アイテムが前のアイテムに依存する場合（累計、イベントのセッション化、ギャップ検出）
• ✅ 複数パスのアルゴリズムや、深さが不明なネストされたデータに対する再帰処理
• ✅ 数千件のアイテムに対する負荷の高い変換で、長いノードチェーンよりも単一ノードのほうが優れている場合（計測済み）

まずはネイティブ機能を使いましょう。合計、平均、件数には → Summarize、並べ替えや順位付けには → Sort + Limit、重複排除には → Remove Duplicates、アイテムを1つの配列にまとめるには → Aggregate、2つのリストを結合するには → Merge。

各アイテムを一度ずつ実行

このモードの用途： 限定的なケースのみ

• 仕組み：入力アイテムごとに、コードを個別に実行します
• データへのアクセス：$input.item または $item
• 最適な用途：アイテム固有のロジック、独立した処理、アイテムごとの検証
• パフォーマンス：大規模なデータセットでは低速です（複数回実行）

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

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

使用する場合：

• ✅ 各アイテムで個別の API 呼び出しが必要な場合
• ✅ エラー処理が異なる、アイテムごとの検証
• ✅ アイテムのプロパティに基づく、アイテム固有の変換
• ✅ ビジネスロジック上、アイテムを個別に処理する必要がある場合

判断の目安：

• 複数のアイテムを確認する必要がありますか？ → 「All Items」モードを使用します
• 各アイテムは完全に独立していますか？ → 「Each Item」モードを使用します
• 判断できませんか？ → 「All Items」モードを使用します（必要に応じて内部でループできます）

「All Items」が高速な理由 — アイテムごとの実行境界

モードの選択は、Code ノードで最も大きくパフォーマンスに影響する要素です。アイテムごとの実行コンテキストには、セットアップのオーバーヘッドがかかります（n8n 2.x で小さなレコードを使って計測）。

アイテムごとに実行される処理	おおよそのコスト
Code All Items（セット全体を一度に実行）	約 0.02 ms／アイテム
任意のノードの式（IF ／ Set など）	約 0.2 ms／アイテム
Code Each Item（アイテムごとに完全なサンドボックスを実行）	約 0.6 ms／アイテム — All Items の約 25～30 倍

そのため、10k 件のアイテムに対して Run Once for Each Item を使うと、純粋なオーバーヘッドだけで約 6 秒かかります。一方、Run Once for All Items なら約 0.2 秒です。各アイテムを分離する必要が実際にある場合（個別のエラー処理や、バッチ化できないアイテムごとの API 呼び出し）に限って Each Item を使い、それ以外は 1 つの All Items ノード内でループしてください。式の複雑さによるコストは実質的に無視できます（コストの約 90％はコードではなく、アイテムごとのコンテキストに起因します）。また、ノード間の接続をまたぐたびにすべてのアイテムが再コピーされるため、各境界を個別に微調整するのではなく、アイテムごとの実行境界の数を減らしてください。

アイテムごとのコストに加えて、Code ノードを実行するたびにタスクランナーへの固定の引き渡しコストが発生します。デフォルトの内部モードでは、ランナーは 15 秒間アイドル状態が続くと停止します（N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT）。そのため、ワークフローを間隔を空けて実行すると、ほとんどの実行で数百ミリ秒のコールドスタートが発生します。ネイティブの変換ノードは、すべてのアイテムを同一プロセス内の1回の呼び出しで処理し、この引き渡しを省略します。

ノード選択への影響。 ほとんどのワークフローは I/O バウンドであり、数百件未満のアイテムではこれらのコストは問題になりません。読みやすさを基準に選び、まずはネイティブノードを使ってください。パフォーマンスが選択の決め手となるのは、全アイテムに対する負荷の高い処理、つまり1回の実行で数千件のアイテムを処理し、I/O ではなく変換処理が支配的で、ユーザーから指定されているか実測されている場合に限られます。その場合は、1つの All Items Code ノードが長いノードチェーンを上回ることがあり、その理由を Why Code: の注記に記載します。ここに示した数値は、このパックで計測した唯一の参考値です。他のスキルでは繰り返さず、ここを参照します。

参照先：DATA_ACCESS.md → 派生する事項、ノード間の接続コスト、規模の確認については「Mode Performance」を参照してください。

---

データアクセスパターン

上流ノードからデータを取得する4つの方法です。$node["Name"] と $('Name') には .first().json または .all() が必要です。.json を直接使わないでください。

const allItems = $input.all();          // 1. All items — batch ops, aggregation (most common)
const data = $input.first().json;       // 2. First item — single objects, API responses
const item = $input.item;               // 3. Current item — "Each Item" mode ONLY (undefined otherwise)
const other = $node["Webhook"].json;    // 4. Named node — combine data across nodes

フィールドには必ず .json 経由でアクセスしてください（例：item.json.name。item.name ではありません）。また、単独の $json.field より、明示的な $input.first().json.field を優先してください。

参照：DATA_ACCESS.md で完全なガイドをご覧ください。各パターンの例、判断ツリー、よくある間違い（元データの変更、長さチェックの漏れ、誤ったモードでの $input.item の使用）を掲載しています。

---

重要：Webhook のデータ構造

最もよくある間違い：Webhook のデータは .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;

理由：Webhook ノードは、すべてのリクエストデータを body プロパティの下に格納します。POST データ、クエリパラメーター、JSON ペイロードが含まれます。

参照：DATA_ACCESS.md で Webhook のデータ構造の詳細をご覧ください。

---

戻り値の形式要件

標準形式：[{json: {...}}] — それぞれに json プロパティを持つオブジェクトの配列です。曖昧さがなく、どちらの実行モードでも同じように動作するため、デフォルトとして使用してください。

Run Once for All Items モードでは、n8n は出力時に、より緩い形式を自動的に正規化します。単一の json のないオブジェクトや、json のないオブジェクトの配列は、自動的に json の下にラップされます。そのため、return {foo: 1} も実行できます。ラップするものがなく、実行時に「Code doesn't return items properly」というエラーが実際に発生するのは、プリミティブ（文字列／数値／ブール値）または null／undefined です。（n8n-mcp ≥ 2.63.0 では、この自動ラップ動作を反映し、json のないオブジェクトを返してもエラーとして警告されなくなりました。）

正しい戻り値の形式

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

// ✅ Multiple results
return [
  {json: {id: 1, data: 'first'}},
  {json: {id: 2, data: 'second'}}
];

// ✅ Transformed array
const transformed = $input.all()
  .filter(item => item.json.valid)
  .map(item => ({
    json: {
      id: item.json.id,
      processed: true
    }
  }));
return transformed;

// ✅ Empty result (when no data to return)
return [];

// ✅ Conditional return
if (shouldProcess) {
  return [{json: processedData}];
} else {
  return [];
}

標準ではない戻り値（自動ラップされますが、標準形式を推奨します）

// ⚠️ Auto-wrapped in All Items mode → [{json: {field: value}}]. Runs, but prefer the array form.
return {
  json: {field: value}
};

// ⚠️ Auto-wrapped → [{json: {field: value}}]. Runs, but add the json wrapper for clarity.
return [{field: value}];

// ✅ Fine — input items already carry a json property, so returning them unchanged is a valid passthrough
return $input.all();

実際に正しくない戻り値

// ❌ FAILS: primitive — n8n errors "Code doesn't return items properly"
return "processed";

// ❌ FAILS: null / undefined — nothing to pass to the next node
return null;

重要な理由：標準形式の [{json: {...}}] は曖昧さがなく、どちらのモードでも同じように動作します。n8n は All Items モードで json のないオブジェクトやオブジェクトの配列を自動的に正規化しますが、プリミティブや null の戻り値にはラップするものがなく、実行が停止します。

参照：ERROR_PATTERNS.md の #3 で、エラーの詳しい解決方法をご覧ください。

---

よく使われるパターンの概要

Code ノードが条件を満たした場合に使える、本番ワークフローで特に便利な Code ノードの形式です。いくつかの処理にはネイティブな代替手段があります（合計 → Summarize、上位N件 → Sort + Limit、JSON 比較 → Compare Datasets、文字列の集約 → Aggregate または Summarize の concatenate）。ライブラリ内の各パターンでは、最初にネイティブな代替手段を紹介しています。ライブラリ全体では、複数ソースの集約、正規表現によるフィルタリング、Markdown／構造化テキストの解析、JSON 比較、CRM／フォームの変換、リリース処理、計算フィールドを使った配列変換、Slack Block Kit のフォーマット、上位N件のランキング、文字列集約レポートの10パターンを、それぞれバリエーションとともに取り上げています。

参照：COMMON_PATTERNS.md で、本番環境向けの詳しい10パターンと、ベストプラクティスのセクション（入力の検証、try-catch、早めのフィルタリング、ループより配列メソッドを使う方法、console.log によるデバッグ）をご覧ください。

---

エラーの防止 - よくある間違い

Code ノードで繰り返し発生する失敗を、おおよその頻度順に示します。

1. コードが空／return がない — 必ず最後に return [...] を記述し、すべての分岐で値を返すようにしてください。
2. 式の構文をコードとして使用 — JavaScript を記述する場所に {{ }} を書かないでください（return {{ $json.x }} は構文エラーです）。`${$json.field}` または $input.first().json.field を使用してください。文字列リテラル内の {{ }} は問題ありません。n8n が評価しない、単なる文字列です。
3. 戻り値の形式 — return [{json:{...}}] を推奨します。単独の return {…} は All Items モードで自動的にラップされますが、実際にエラーになるのはプリミティブ値（文字列／数値）や null を返した場合です。
4. null チェックがない — オプショナルチェーンを使用してください：item.json?.user?.email || 'fallback'。
5. Webhook の本文のネスト — $json.email は未定義です。$json.body.email を使用してください。
6. 認証ヘルパーがブロックされる（httpRequestWithAuthentication）および $env がブロックされる — シークレットは Code ノードのサンドボックスではなく、クレデンシャル／HTTP Request ノード経由で扱ってください。

参照：ERROR_PATTERNS.md には包括的なガイドがあります。各エラーの誤ったコードと正しいコード、エスケープのルール、サンドボックスの制限（エラー #6～#7）、防止チェックリスト、エラーメッセージのクイック検索表を掲載しています。

---

組み込み関数とヘルパー

// HTTP requests (no auth — see sandbox note below)
const res = await this.helpers.httpRequest({ method: 'GET', url: 'https://api.example.com/data' });

// DateTime (Luxon): now, formatting, arithmetic
const now = DateTime.now();
const formatted = now.toFormat('yyyy-MM-dd');
const tomorrow = now.plus({ days: 1 });

// $jmespath() — query JSON structures
const adults = $jmespath($input.first().json, 'users[?age >= `18`]');

// $getWorkflowStaticData() — data that persists across executions

サンドボックス（n8n v2.0 の JsTaskRunnerSandbox 以降）：アクセサーは this.helpers.httpRequest() です。この環境では $helpers グローバルは未定義です（$helpers.httpRequest() は ReferenceError をスローします）。this が失われるネストされた非同期関数内では、await fn.call(this, ...) のように呼び出してください。this.helpers.httpRequestWithAuthentication と this.helpers.requestWithAuthenticationPaginated は拒否リストに登録されています（→ UnsupportedFunctionError）。認証付きの呼び出しには、クレデンシャルを設定した HTTP Request ノード（推奨）、サブワークフロー、またはトークンがすでにワークフロー内をデータとして流れている場合に限り this.helpers.httpRequest() に手動で Authorization: Bearer ${token} ヘッダーを指定する方法を使用してください。N8N_BLOCK_ENV_ACCESS_IN_NODE=true の場合、$env はブロックされます。require() が機能するのは、許可リストに登録されたモジュールのみです。Buffer、URL、および標準の JavaScript グローバル（Math、JSON、Object、Array）は常に使用できます。

参照：BUILTIN_FUNCTIONS.md には完全なリファレンスがあります。httpRequest の全オプション、DateTime／Luxon のすべての操作、JMESPath のパターン、静的データの使用例、サンドボックス制限の詳細を掲載しています。

---

ベストプラクティス

• 最初に入力を検証する — 処理の前に、配列が空でないか、.json が存在するかを確認してください。
• リスクのある処理（HTTP 呼び出しなど）は try-catch で囲む。クラッシュさせず、エラーオブジェクトを返してください。
• 手動のループより配列メソッド（filter／map／reduce）を優先してください。
• 早めにフィルタリングし、変換は後で行う — コストのかかる処理の前にデータセットを絞り込んでください。
• わかりやすい名前を付け、デバッグには console.log() を使用してください（出力はブラウザーのコンソールに表示されます）。

参照：COMMON_PATTERNS.md →「ベストプラクティス」には、それぞれのコード例があります。

---

本番環境での注意点

実際のデプロイで得られた貴重な教訓を、DATA_ACCESS.md →「本番環境での注意点」にコードとともにまとめています。

• SplitInBatches の出力は直感に反します：main[0] = 完了（すべてのバッチ処理後に一度だけ実行）、main[1] = 各バッチ（ループ本体）です。安全対策として、完了出力の後に Limit 1 ノードを追加してください。
• コストを左右するのは反復回数です：ループの各反復では、エンジンを通じて本体全体が再実行されます（毎回約 0.8 ms のオーバーヘッド）。batchSize: 1 は Each Item に相当するループです。実際の制約（レート制限、ページサイズ、メモリ）が許す最大のバッチサイズを使用するか、そもそもループを使わないでください。
• 反復をまたいだ蓄積（重大）：ループの後に $('Node Inside Loop').all() を呼び出すと、最後の反復のアイテムだけが返されます。$getWorkflowStaticData('global') を使って蓄積してください（ループの前にリセットし、ループ内で追加し、ループの後に読み取ります）。
• pairedItem：入力と 1 対 1 に対応しないアイテムを出力する場合は、pairedItem: { item: i } を設定してください。設定しないと、後続の Set ノードで paired_item_no_info エラーが発生します。
• ノード参照の構文：$('Node').first().json または $('Node').all() を使います。参照に対して .json を直接使わないでください。
• 浮動小数点の精度：浮動小数点の誤差による誤検知を避けるため、通貨はセント単位で比較してください。Math.round(a*100) !== Math.round(b*100) を使います。

---

Code Node を使うタイミング

Code は最後の選択肢です。サービス独自のノード、目的に合った標準ノード、そのノード内の短い式を検討した後に使ってください。 このスキルの最初にある基準が判断テストです。以下は、そのテストで確認される項目です。

Code が適切な場合	例	Code を使わない場合
ノードでは表現できないループや再帰	深さが不明なツリーをフラット化する、複数パスでマッチングする	1 段階のネスト → Split Out
実行間で状態を保持する	$getWorkflowStaticData を使ったカウンターやカーソル	「新しいアイテムのみ」 → 実行間の重複を Remove Duplicates で削除する
対応するノードがない形式を解析する	固定長レコード、カスタムログ形式	CSV／XLSX／PDF／XML／HTML → Extract From File、XML、HTML
許可リストにあるライブラリ	インスタンスで許可されている require('some-lib')	ハッシュ化／HMAC／UUID → Crypto
全アイテムを対象にした負荷の高い処理	数千アイテム、変換処理がボトルネック、明示または計測済み	数百アイテム程度 → 標準ノード
4 つ以上の連携用ノードを置き換える短いノード 1 つ	データの形を変えるだけの Set → Split Out → Set → Aggregate の連鎖を置き換える約 15 行	実際のルーティングや I/O を含む連鎖

一覧にないものは Code を使いません。フィルタリング（Filter）、ルーティング（IF／Switch）、合計と件数（Summarize）、上位 N 件（Sort + Limit）、重複削除（Remove Duplicates）、結合（Merge）、差分（Compare Datasets）、日付（Date & Time または Luxon の式）、API 呼び出しとページング（HTTP Request）、暗号処理と XML（Crypto、XML）が該当します。

残す各 Code ノードには、Why Code: <native node considered> — <reason> というメモを付けます（notes を設定し、キャンバスに表示するには notesInFlow: true を設定してください）。create／update フックは、このメモがない Code ノードを検出すると通知します。

---

他のスキルとの連携

連携するスキル：

n8n Expression Syntax：

• 他のノードでは {{ }} 構文を使います
• Code ノードでは JavaScript を直接使います（{{ }} は使いません）
• 式とコードの使い分け

n8n MCP Tools Expert：

• Code ノードの検索方法：search_nodes({query: "code"})
• 設定のヘルプの取得：get_node({nodeType: "nodes-base.code"})
• コードの検証：validate_node({nodeType: "nodes-base.code", config: {...}})

n8n Node Configuration：

• モードの選択（All Items と Each Item）
• 言語の選択（JavaScript と Python）
• プロパティ間の依存関係の理解

n8n Workflow Patterns：

• 変換ステップでの Code ノード
• Webhook → Code → API パターン
• ワークフローでのエラー処理

n8n Validation Expert：

• Code ノードの設定の検証
• 検証エラーの処理
• よくある問題の自動修正

---

クイックリファレンスチェックリスト

Code ノードをデプロイする前に、次の項目を確認してください。

• ゲートを通過している - 適したネイティブノードがなく、notes が Why Code: で始まっている
• コードが空ではない - 意味のあるロジックを記述する必要があります
• return 文がある - プリミティブ値やnullではなく、アイテムを返します
• 標準的な戻り値の形式である - 各アイテムは {json: {...}} です（オブジェクトのみでも自動的にラップされますが、明示してください）
• データに正しくアクセスしている - $input.all()、$input.first()、または$input.itemを使用しています
• {{ }} をコードとして記述していない - JavaScript のテンプレートリテラルを使用します：`${value}`
• エラー処理をしている - null／undefined の入力に対するガード節があります
• Webhook データを扱っている - Webhook 由来のデータには .body 経由でアクセスします
• モードを選択している - ほとんどの場合、「All Items」を使用します
• パフォーマンスを考慮している - 手動ループよりも map/filter を優先します
• 出力に一貫性がある - すべてのコードパスで同じ構造を返します

---

その他のリソース

関連ファイル

• DATA_ACCESS.md - データアクセスパターンの詳細
• COMMON_PATTERNS.md - 本番環境で検証済みの10個のパターン
• ERROR_PATTERNS.md - よくある上位5つのエラーと解決策
• BUILTIN_FUNCTIONS.md - 組み込み機能の完全なリファレンス

n8n のドキュメント

• Code ノードガイド：https://docs.n8n.io/code/code-node/
• 組み込みメソッド：https://docs.n8n.io/code-examples/methods-variables-reference/
• Luxon ドキュメント：https://moment.github.io/luxon/

---

n8n の Code ノードで JavaScript を書く準備ができました！ まずは簡単な変換から始め、よくあるミスを避けるためにエラーパターンガイドを活用し、本番環境ですぐに使える例についてはパターンライブラリを参照してください。