- Spezifische API-Integration: Sie müssen sich mit einer internen API oder einem spezialisierten System verbinden, für das es keinen Standard-Node gibt.
- Komplexe Daten-Transformation: Sie benötigen Transformationen, die über Set-, Filter- und Code-Nodes hinausgehen.
- Wiederverwendbare Geschäftslogik: Bestimmte Geschäftsregeln werden in vielen Workflows verwendet und sollen als ein Node gekapselt sein.
Aufbau eines Nodes
Jeder Node implementiert dasINodeType-Interface: description definiert Anzeigename, Inputs/Outputs, Credentials und die konfigurierbaren Properties; execute enthält die Logik.
Node-Struktur
Die Code-Skelette für Trigger- und Webhook-Nodes stehen in der n8n-Dokumentation — das Beispiel unten zeigt einen Regular Node.
Entwicklungsumgebung einrichten
Voraussetzungen: Node.js 18+, TypeScript (npm install -g typescript), Git und ein Code-Editor (VS Code empfohlen).
1
Projekt-Verzeichnis erstellen
2
package.json anlegen
Initialisieren Sie mit
npm init -y und bearbeiten Sie die package.json. Der n8n-Block registriert Ihre Nodes:package.json
3
TypeScript konfigurieren
tsconfig.json
4
Abhängigkeiten installieren
Beispiel: Localmind Agent Node
Ein vollständiger Custom Node, der Localmind-Agenten über den OpenAI-kompatiblen/v1-Endpoint aufruft (model trägt die Agent-UUID):
nodes/LocalmindAgent/LocalmindAgent.node.ts
getInputData() liest die Input-Items, getNodeParameter() liest die Node-Konfiguration, returnData.push({ json: ... }) erzeugt den Output. Für Fehlerbehandlung pro Item prüfen Sie this.continueOnFail() — ist die Option aktiv, geben Sie den Fehler als Item weiter statt die Execution abzubrechen (Details: n8n-Dokumentation).
Credentials definieren
Für die API-Authentifizierung definieren Sie einen Credential-Typ. Als API-Key verwenden Sie einen persönlichen User-API-Key (sk-…), den Sie unter Benutzereinstellungen → API-Schlüssel erstellen — optional auf einzelne Spaces gescoped (siehe Persönliche API-Schlüssel):
credentials/localmindApi.credentials.ts
Properties
Properties sind die konfigurierbaren Parameter Ihres Nodes. Nebenstring und number (siehe Beispiel oben) gibt es unter anderem options für Dropdown-Auswahlen und collection für Key-Value-Sammlungen; gesteuert wird das Verhalten über Felder wie required, default, placeholder und typeOptions (etwa minValue, maxValue, numberStepSize). Die vollständige Liste aller Property-Typen dokumentiert die n8n-Referenz.
Einen direkten SQL-/Datenbank-Zugriff auf Localmind gibt es nicht. Daten in Spaces erreichen Sie ausschließlich über die Localmind API — zum Beispiel über die Dokument- und Such-Endpoints (siehe Dokumente und Suche).
Testen
Kompilieren Sie den Node mitnpm run build und testen Sie ihn lokal im Automate Dev-Modus. Ergänzen Sie Unit Tests für die Node-Logik (z.B. test/LocalmindAgent.test.ts mit einem Test-Framework Ihrer Wahl) und Integration Tests in echten Workflows: Test-Workflow erstellen, mit Test-Daten ausführen, Outputs überprüfen. Wie Sie Nodes und Workflows systematisch testen, steht unter Testing.
Deployment
- Build erstellen:
npm run buildkompiliert TypeScript zu JavaScript. - Package erstellen:
npm packerzeugt eine installierbare.tgz-Datei. - Node installieren: im Automate-Verzeichnis
npm install /path/to/localmind-custom-node-1.0.0.tgzausführen.
Best Practices
- Dokumentation: jeden Property und jede Funktion klar beschreiben (
description-Felder pflegen). - Error Handling: alle Fehlerfälle abfangen,
continueOnFail()unterstützen. - Performance: unnötige API-Calls vermeiden.
- Wiederverwendbarkeit: Nodes so designen, dass sie in verschiedenen Kontexten funktionieren.
- Testing: Unit- und Integration-Tests schreiben.
- Versionierung: semantische Versionierung verwenden.
Häufige Probleme
Nächste Schritte
n8n Dokumentation
Offizielle Referenz für Custom Nodes: Property-Typen, Trigger-/Webhook-Skelette, UI-Elemente.
Localmind API
Endpoint-Referenz und Code-Beispiele für Integrationen.
