TL;DR: n8n ist ein mächtiges Automatisierungstool, aber manchmal reichen die mitgelieferten Nodes nicht aus. In diesem Artikel zeige ich dir, wie du eigene Custom Nodes mit TypeScript entwickelst, lokal testest und per npm oder Docker in deine n8n-Instanz bringst.

🤔 Warum Custom Nodes?

n8n bietet hunderte von Nodes für die verschiedensten Services und Integrationen. Aber was, wenn du eine interne API anbinden willst, die niemand kennt? Oder wenn du eine ganz spezifische Datenverarbeitung brauchst, die kein existierender Node abdeckt? Genau dafür gibt es Custom Nodes – du erweiterst n8n einfach mit deiner eigenen Logik.

🧩 Was sind Custom Nodes?

Custom Nodes sind eigene n8n-Erweiterungen, die du in TypeScript schreibst. Sie verhalten sich genauso wie die eingebauten Nodes: Sie erscheinen im Node-Menü, haben Eingabefelder, können Credentials nutzen und lassen sich in Workflows einbauen.

Technisch gesehen implementierst du das INodeType-Interface von n8n und exportierst deinen Node als npm-Paket. n8n erkennt das Paket und lädt es beim Start automatisch.

📋 Voraussetzungen

Bevor du loslegst, brauchst du folgende Tools:

• Node.js (ab Version 18)
• TypeScript – Custom Nodes werden in TypeScript geschrieben
• n8n CLI – installiert über npm install -g n8n
• n8n-node-dev – das offizielle Scaffolding-Tool: npx n8n-node-dev
• Optional: Docker, wenn du deine Nodes in einem Container betreiben willst

🏗️ Projekt-Setup

Der schnellste Weg, ein neues Node-Projekt aufzusetzen, ist das offizielle Scaffolding:

# Neues Node-Projekt erstellen
npx n8n-node-dev new

# Alternativ: Starter-Template klonen
git clone https://github.com/n8n-io/n8n-nodes-starter.git
cd n8n-nodes-starter
npm install

Die Ordnerstruktur sieht dann so aus:

my-n8n-nodes/
├── credentials/
│   └── MyApiCredentials.credentials.ts
├── nodes/
│   └── MyNode/
│       ├── MyNode.node.ts
│       └── myNode.svg          # Icon
├── package.json
├── tsconfig.json
└── index.ts

Wichtig ist die package.json: Hier definierst du unter dem Key n8n, welche Nodes und Credentials dein Paket bereitstellt:

{
  "name": "n8n-nodes-my-custom",
  "version": "0.1.0",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": [
      "dist/nodes/MyNode/MyNode.node.js"
    ],
    "credentials": [
      "dist/credentials/MyApiCredentials.credentials.js"
    ]
  }
}

🔬 Anatomie eines Nodes

Jeder Custom Node implementiert das INodeType-Interface. Das Herzstück besteht aus zwei Teilen:

1. description – Metadaten, Eingabefelder und die Konfiguration des Nodes
2. execute() – die Methode, die bei der Ausführung aufgerufen wird

💻 Code-Beispiel: Ein einfacher HTTP-Request-Node

Hier ein vollständiges Beispiel für einen Custom Node, der eine HTTP-Anfrage an eine API macht:

import {
  IExecuteFunctions,
  INodeExecutionData,
  INodeType,
  INodeTypeDescription,
} from 'n8n-workflow';

export class MyHttpNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'My HTTP Node',
    name: 'myHttpNode',
    group: ['transform'],
    version: 1,
    description: 'Macht einen einfachen HTTP-Request',
    defaults: {
      name: 'My HTTP Node',
    },
    inputs: ['main'],
    outputs: ['main'],
    credentials: [
      {
        name: 'myApiCredentials',
        required: true,
      },
    ],
    properties: [
      {
        displayName: 'Endpoint',
        name: 'endpoint',
        type: 'string',
        default: '/api/data',
        placeholder: '/api/endpoint',
        description: 'Der API-Endpoint, der aufgerufen werden soll',
      },
      {
        displayName: 'Method',
        name: 'method',
        type: 'options',
        options: [
          { name: 'GET', value: 'GET' },
          { name: 'POST', value: 'POST' },
        ],
        default: 'GET',
        description: 'Die HTTP-Methode',
      },
    ],
  };

  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
    const items = this.getInputData();
    const returnData: INodeExecutionData[] = [];

    const credentials = await this.getCredentials('myApiCredentials');
    const baseUrl = credentials.baseUrl as string;
    const apiKey = credentials.apiKey as string;

    for (let i = 0; i < items.length; i++) {
      const endpoint = this.getNodeParameter('endpoint', i) as string;
      const method = this.getNodeParameter('method', i) as string;

      const response = await this.helpers.request({
        method,
        url: `${baseUrl}${endpoint}`,
        headers: {
          'Authorization': `Bearer ${apiKey}`,
        },
        json: true,
      });

      returnData.push({ json: response });
    }

    return [returnData];
  }
}

🔑 Credentials definieren

Damit dein Node API-Keys oder andere Zugangsdaten verwenden kann, erstellst du einen Credential Type. Dieser implementiert das ICredentialType-Interface:

import {
  ICredentialType,
  INodeProperties,
} from 'n8n-workflow';

export class MyApiCredentials implements ICredentialType {
  name = 'myApiCredentials';
  displayName = 'My API Credentials';
  properties: INodeProperties[] = [
    {
      displayName: 'Base URL',
      name: 'baseUrl',
      type: 'string',
      default: 'https://api.example.com',
    },
    {
      displayName: 'API Key',
      name: 'apiKey',
      type: 'string',
      typeOptions: { password: true },
      default: '',
    },
  ];
}

Die Credentials werden von n8n verschlüsselt gespeichert. Nutzer können sie über die UI eingeben, und in deinem Node greifst du mit this.getCredentials('myApiCredentials') darauf zu.

🧪 Lokal testen

Zum lokalen Testen verlinkst du dein Node-Paket einfach mit npm link:

# Im Node-Projekt
npm run build
npm link

# Im n8n-Installationsverzeichnis
cd ~/.n8n
npm link n8n-nodes-my-custom

# n8n starten
n8n start

Dein Node sollte jetzt im Node-Menü von n8n erscheinen. Änderungen am Code musst du nach einem npm run build und n8n-Neustart testen.

Tipp: Nutze n8n-node-dev build --watch für automatisches Rebuilden bei Änderungen.

🐳 Publishing & Docker

Wenn dein Node fertig ist, hast du zwei Möglichkeiten, ihn zu verteilen:

Option 1: npm veröffentlichen

# Package veröffentlichen
npm publish

# Andere können es dann installieren
cd ~/.n8n
npm install n8n-nodes-my-custom

Wichtig: Der Paketname muss mit n8n-nodes- beginnen, damit n8n ihn automatisch erkennt!

Option 2: Docker

Für Docker-basierte n8n-Installationen erstellst du ein eigenes Dockerfile:

FROM n8nio/n8n:latest

# Custom Nodes installieren
USER root
RUN cd /usr/local/lib/node_modules/n8n && \
    npm install n8n-nodes-my-custom
USER node

Oder du mountest die Nodes direkt ins Volume:

# docker-compose.yml
services:
  n8n:
    image: n8nio/n8n
    volumes:
      - n8n_data:/home/node/.n8n
      - ./custom-nodes:/home/node/.n8n/nodes

🎯 Fazit

Custom Nodes sind ein mächtiges Feature von n8n, das dir erlaubt, die Plattform genau an deine Bedürfnisse anzupassen. Mit TypeScript und dem INodeType-Interface hast du volle Kontrolle über die Logik, die UI-Felder und die Credential-Verwaltung.

Der Workflow ist dabei überraschend einfach:

1. Projekt mit n8n-node-dev aufsetzen
2. Node-Klasse mit description und execute() implementieren
3. Lokal testen mit npm link
4. Per npm oder Docker veröffentlichen

Viel Spaß beim Bauen deiner eigenen Nodes! 🚀