Building n8n Custom Nodes: The Guide I Wish I Had

n8n supports two node styles. Declarative nodes are JSON-ish descriptions of an HTTP request; n8n handles the fetch, auth, and error mapping. Programmatic nodes give you an execute() function where you write TypeScript directly.

Rule of thumb: if your integration is one HTTP call per operation and returns JSON, go declarative — you'll finish in an hour and the node will keep working when n8n upgrades. If you need pagination loops, streaming, binary data, or conditional branching, go programmatic.

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

export class Acme implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'Acme',
    name: 'acme',
    icon: 'file:acme.svg',
    group: ['transform'],
    version: 1,
    description: 'Interact with the Acme API',
    defaults: { name: 'Acme' },
    inputs: ['main'],
    outputs: ['main'],
    credentials: [{ name: 'acmeApi', required: true }],
    requestDefaults: {
      baseURL: 'https://api.acme.io/v1',
      headers: { 'Content-Type': 'application/json' },
    },
    properties: [
      { displayName: 'Resource', name: 'resource', type: 'options',
        options: [{ name: 'Customer', value: 'customer' }], default: 'customer', noDataExpression: true },
      { displayName: 'Operation', name: 'operation', type: 'options',
        displayOptions: { show: { resource: ['customer'] } },
        options: [{ name: 'Get', value: 'get', action: 'Get a customer',
          routing: { request: { method: 'GET', url: '=/customers/{{$parameter.id}}' } } }],
        default: 'get', noDataExpression: true },
      { displayName: 'Customer ID', name: 'id', type: 'string', default: '',
        displayOptions: { show: { resource: ['customer'], operation: ['get'] } } },
    ],
  };
}

That's a working node. No execute(), no manual fetch, no error handling — n8n does all of it from the routing declaration.

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

export class AcmeApi implements ICredentialType {
  name = 'acmeApi';
  displayName = 'Acme API';
  properties: INodeProperties[] = [
    { displayName: 'API Key', name: 'apiKey', type: 'string', typeOptions: { password: true }, default: '' },
  ];
  authenticate = {
    type: 'generic' as const,
    properties: { headers: { Authorization: '=Bearer {{$credentials.apiKey}}' } },
  };
  test = {
    request: { baseURL: 'https://api.acme.io/v1', url: '/whoami' },
  };
}

The test block powers the 'Test connection' button in the UI. Ship it — users will thank you the first time they mistype a key.

async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
  const out: INodeExecutionData[] = [];
  let cursor: string | undefined;
  do {
    const res = await this.helpers.httpRequestWithAuthentication.call(this, 'acmeApi', {
      method: 'GET',
      url: 'https://api.acme.io/v1/orders',
      qs: { cursor, limit: 200 },
      json: true,
    });
    for (const item of res.data) out.push({ json: item });
    cursor = res.next_cursor;
  } while (cursor);
  return [out];
}

Always cap the loop (e.g. while (cursor && out.length < 50_000)) and expose a limit parameter. Runaway pagination is the most common way custom nodes take down an n8n instance.

If your node fetches or produces files, use n8n's binary helpers instead of loading everything into a JS Buffer:

const stream = await this.helpers.httpRequest({ method: 'GET', url, encoding: 'stream' });
const binary = await this.helpers.prepareBinaryData(stream, fileName, mimeType);
return [[{ json: {}, binary: { data: binary } }]];

This streams to n8n's configured binary storage (filesystem or S3) instead of the workflow's JSON payload. On queue-mode installs, this is the difference between a working node and OOM-killed workers.

1. Package name must start with n8n-nodes- (e.g. n8n-nodes-acme).
2. Set n8n field in package.json pointing to dist/nodes and dist/credentials.
3. Add keyword n8n-community-node-package — this is what the installer searches for.
4. Run npm run build (tsc + copy icons), then npm publish --access public.
5. In n8n Settings → Community Nodes → Install, paste the package name.

Version aggressively. If you change a parameter name or an operation's response shape, bump major and document the migration. n8n users cannot 'roll back' a workflow the way developers roll back code.