n8nのカスタムノード開発入門：独自の連携機能を作る方法

n8nのカスタムノードをTypeScriptで開発する方法をステップバイステップで解説。プロジェクト作成からnpm公開まで、実践的なガイド。

#n8n

#API

#TypeScript

n8nには、数百もの標準ノードが用意されており、主要なSaaSやデータベースとの連携はすぐに始めることができます。しかし、もし連携したいサービスがリストにない場合はどうすればよいでしょうか？特に、自社で開発した独自の社内システムや、ニッチな業界特化型ツールと連携したい場合、標準ノードだけでは対応できません。

ここで真価を発揮するのが、n8nのオープンソースならではの強み、カスタムノード開発です。n8nでは、開発者が自分で新しいノードを作成し、n8nの機能を無限に拡張することができます。

本記事では、カスタムノード開発の第一歩として、その基本的な仕組みと開発プロセスを、私たちHumanoidが分かりやすく解説します。

カスタムノードとは？

カスタムノードは、TypeScript（JavaScriptのスーパーセット）で記述されたプログラムです。n8nのノード開発フレームワークに従ってコードを書くことで、n8nのUI上に新しいノードとして表示され、他のノードと同じようにワークフローに組み込むことができます。

カスタムノードを開発することで、以下のようなことが可能になります。

社内システムとの連携: 社内の顧客管理システム（CRM）や在庫管理システムと連携するノードを作成し、n8nから直接データを読み書きする。
特殊なAPIへの対応: 標準のHTTP Requestノードでは対応が難しい、複雑な認証方式やデータ形式を持つAPIと連携する。
定型処理の共通化: 複数のワークフローで共通して使う一連の処理（例：特定の形式でのデータ整形や計算）を一つのノードにまとめることで、ワークフローをシンプルにし、再利用性を高める。

詳しはこちらから

カスタムノード開発の3ステップ

カスタムノードの開発は、Node.jsとnpm（Node.jsのパッケージマネージャー）の基本的な知識があれば、誰でも始めることができます。

ステップ1：開発環境のセットアップ

n8nは、カスタムノード開発を簡単にするためのコマンドラインツール（CLI）を提供しています。まず、n8n-node-devをインストールし、新しいノードの雛形を作成します。

# CLIツールをインストール
npm install n8n-node-dev -g
 
# 新しいノードプロジェクトを作成
n8n-node-dev new

これにより、ノードの基本的なファイル構成が自動で生成されます。

ステップ2：ノードの定義とロジックの実装

生成されたファイルの中で、最も重要なのは*.node.tsという名前のファイルです。このファイルに、ノードの見た目（プロパティ）と動作（ロジック）を定義します。

ノードの定義 (Properties): ノードのUIに表示される入力フィールド（テキストボックス、ドロップダウンリストなど）を定義します。例えば、APIのエンドポイントを入力するフィールドや、認証情報を設定するクレデンシャルフィールドなどを指定します。

カスタムノードのプロパティ定義コードの例

ロジックの実装 (Execute Method): executeメソッドの中に、ノードが実行されたときの実際の処理を記述します。ここで、入力フィールドの値を取得し、外部APIを呼び出し、その結果を整形して後続のノードに渡す、といったロジックを実装します。

// executeメソッドの実装例
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
  const items = this.getInputData();
  let responseData;
  const returnData = [];
 
  for (let i = 0; i < items.length; i++) {
    const endpoint = this.getNodeParameter('endpoint', i, '') as string;
    
    // 外部APIを呼び出す処理
    responseData = await this.helpers.httpRequest({
      method: 'GET',
      url: `https://api.example.com/${endpoint}`,
    });
 
    returnData.push({ json: responseData });
  }
 
  return [this.helpers.returnJsonArray(returnData)];
}

ステップ3：ビルドとインストール

コードが完成したら、ビルドしてn8nにインストールします。

# コードをビルド
npm run build
 
# n8nにインストール（n8nをセルフホスティングしている場合）
# .n8n/custom/フォルダにビルドしたファイルをコピー

n8nを再起動すると、ノードパレットに新しく作成したカスタムノードが表示されます。

Humanoidの見解：自動化の「最後の1ピース」を埋める

標準ノードとHTTP Requestノードを組み合わせれば、多くの自動化は実現できます。しかし、ビジネスが成長し、プロセスが複雑化するにつれて、必ず「標準機能だけでは手が届かない」領域が出てきます。カスタムノード開発は、その「最後の1ピース」を埋め、真にシームレスな自動化を実現するための鍵となります。

パズルの最後の1ピースがはまるイメージ