n8n Community Node Creation

Build production-ready n8n community nodes as npm packages. This skill covers both declarative (REST API wrapping) and programmatic (custom logic) node styles.

References: CREDENTIAL_PATTERNS.md | TRIGGER_PATTERNS.md | EXAMPLES.md | COMMON_MISTAKES.md

Quick Reference: Declarative vs Programmatic

Decision rule: If every operation is a single HTTP request with simple input→body mapping and the response can be used as-is (or with minor postReceive transforms), use declarative. Otherwise, use programmatic.

Getting Started

IMPORTANT: Always start by cloning the official n8n-nodes-starter repository. Do NOT scaffold a project from scratch. The starter provides the correct TypeScript config, build tooling, linting, and project structure that n8n expects.

1. Clone the n8n-nodes-starter (Mandatory First Step)

# Clone the official starter — this is always the first step
git clone https://github.com/n8n-io/n8n-nodes-starter.git n8n-nodes-<yourservice>
cd n8n-nodes-<yourservice>

# Remove the starter's git history and reinitialize
rm -rf .git
git init

# Install dependencies
npm install

The starter repo provides:

• Pre-configured tsconfig.json with the correct compiler options for n8n
• Working package.json with build scripts (build, dev, lint, lintfix)
• ESLint/Prettier configuration matching n8n conventions
• Example node and credential files to use as a starting reference
• Correct n8n object structure in package.json pointing to dist/ outputs

After cloning, rename/replace the example node and credential files with your own, and update package.json with your package name (n8n-nodes-<yourservice>), description, and the n8n.nodes / n8n.credentials arrays.

2. Required Files

Critical rules:

• npm package name must start with n8n-nodes-
• Class name must match filename (class MyService → MyService.node.ts)
• Icon filename is lowercase (myservice.svg)

3. Package.json n8n Config

{
  "name": "n8n-nodes-myservice",
  "version": "0.1.0",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": [
      "dist/nodes/MyService/MyService.node.js"
    ],
    "credentials": [
      "dist/credentials/MyServiceApi.credentials.js"
    ]
  }
}

Node Class Structure

Every node implements INodeType with a description object:

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

export class MyService implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'My Service',
    name: 'myService',
    icon: 'file:myservice.svg',
    group: ['transform'],
    version: 1,
    subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
    description: 'Interact with My Service API',
    defaults: { name: 'My Service' },
    inputs: [NodeConnectionType.Main],
    outputs: [NodeConnectionType.Main],
    credentials: [
      { name: 'myServiceApi', required: true },
    ],
    properties: [
      // Resource and operation selectors, then parameter fields
    ],
  };
}

Required Description Properties

Resource & Operation Pattern

The standard way to organize a node with multiple API resources:

properties: [
  // 1. Resource selector
  {
    displayName: 'Resource',
    name: 'resource',
    type: 'options',
    noDataExpression: true,       // REQUIRED on resource/operation selectors
    options: [
      { name: 'Contact', value: 'contact' },
      { name: 'Deal', value: 'deal' },
    ],
    default: 'contact',
  },
  // 2. Operation selector (per resource)
  {
    displayName: 'Operation',
    name: 'operation',
    type: 'options',
    noDataExpression: true,
    displayOptions: { show: { resource: ['contact'] } },
    options: [
      { name: 'Create', value: 'create', action: 'Create a contact' },
      { name: 'Delete', value: 'delete', action: 'Delete a contact' },
      { name: 'Get', value: 'get', action: 'Get a contact' },
      { name: 'Get Many', value: 'getAll', action: 'Get many contacts' },
      { name: 'Update', value: 'update', action: 'Update a contact' },
    ],
    default: 'create',
  },
  // 3. Operation-specific fields
  {
    displayName: 'Contact ID',
    name: 'contactId',
    type: 'string',
    required: true,
    default: '',
    displayOptions: {
      show: { resource: ['contact'], operation: ['get', 'update', 'delete'] },
    },
    description: 'The ID of the contact',
  },
  // 4. returnAll / limit pair for getAll
  {
    displayName: 'Return All',
    name: 'returnAll',
    type: 'boolean',
    default: false,
    displayOptions: { show: { resource: ['contact'], operation: ['getAll'] } },
    description: 'Whether to return all results or only up to a given limit',
  },
  {
    displayName: 'Limit',
    name: 'limit',
    type: 'number',
    default: 50,
    typeOptions: { minValue: 1 },
    displayOptions: {
      show: { resource: ['contact'], operation: ['getAll'], returnAll: [false] },
    },
    description: 'Max number of results to return',
  },
  // 5. Additional fields (optional params)
  {
    displayName: 'Additional Fields',
    name: 'additionalFields',
    type: 'collection',
    placeholder: 'Add Field',
    default: {},
    displayOptions: { show: { resource: ['contact'], operation: ['create', 'update'] } },
    options: [
      { displayName: 'Email', name: 'email', type: 'string', default: '' },
      { displayName: 'Phone', name: 'phone', type: 'string', default: '' },
    ],
  },
],

Key rules:

• Always set noDataExpression: true on resource and operation selectors
• Always include action on each operation option (used for the node action list)
• Standard operation values: create, get, getAll, update, delete, upsert
• Use displayOptions.show to conditionally display fields per resource/operation

Declarative Style

Add requestDefaults to description and routing to each operation. No execute() method.

description: INodeTypeDescription = {
  // ...standard properties...
  requestDefaults: {
    baseURL: 'https://api.myservice.com/v1',
    headers: { Accept: 'application/json' },
  },
  properties: [
    {
      displayName: 'Operation', name: 'operation', type: 'options',
      noDataExpression: true,
      options: [
        {
          name: 'Create', value: 'create', action: 'Create an item',
          routing: {
            request: { method: 'POST', url: '/items' },
          },
        },
        {
          name: 'Get', value: 'get', action: 'Get an item',
          routing: {
            request: { method: 'GET', url: '=/items/{{$parameter.itemId}}' },
          },
        },
      ],
      default: 'create',
    },
    // Map field values to request body/query
    {
      displayName: 'Name', name: 'name', type: 'string', default: '',
      routing: { send: { type: 'body', property: 'name' } },
    },
    {
      displayName: 'Tag', name: 'tag', type: 'string', default: '',
      routing: { send: { type: 'query', property: 'tag' } },
    },
  ],
};

Routing Keys

postReceive Transforms

routing: {
  output: {
    postReceive: [
      { type: 'rootProperty', properties: { property: 'data' } },     // Extract nested data
      { type: 'filter', properties: { pass: '={{$responseItem.active}}' } },
      { type: 'limit', properties: { maxResults: '={{$parameter.limit}}' } },
      { type: 'set', properties: { value: '={{ { "id": $response.body.id } }}' } },
    ],
  },
},

Programmatic Style

Add an async execute() method for full control:

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

export class MyService implements INodeType {
  description: INodeTypeDescription = { /* ...same as above, minus requestDefaults/routing... */ };

  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
    const items = this.getInputData();
    const returnData: INodeExecutionData[] = [];
    const resource = this.getNodeParameter('resource', 0) as string;
    const operation = this.getNodeParameter('operation', 0) as string;

    for (let i = 0; i < items.length; i++) {
      try {
        let responseData;

        if (resource === 'contact') {
          if (operation === 'create') {
            const email = this.getNodeParameter('email', i) as string;
            const additionalFields = this.getNodeParameter('additionalFields', i) as IDataObject;
            const body: IDataObject = { email, ...additionalFields };
            responseData = await myServiceApiRequest.call(this, 'POST', '/contacts', body);
          }
          if (operation === 'getAll') {
            const returnAll = this.getNodeParameter('returnAll', i) as boolean;
            if (returnAll) {
              responseData = await myServiceApiRequestAllItems.call(
                this, 'contacts', 'GET', '/contacts',
              );
            } else {
              const limit = this.getNodeParameter('limit', i) as number;
              responseData = await myServiceApiRequest.call(
                this, 'GET', '/contacts', {}, { limit },
              );
              responseData = responseData.contacts;
            }
          }
        }

        const executionData = this.helpers.constructExecutionMetaData(
          this.helpers.returnJsonArray(responseData),
          { itemData: { item: i } },
        );
        returnData.push(...executionData);

      } catch (error) {
        if (this.continueOnFail()) {
          const executionErrorData = this.helpers.constructExecutionMetaData(
            this.helpers.returnJsonArray({ error: error.message }),
            { itemData: { item: i } },
          );
          returnData.push(...executionErrorData);
          continue;
        }
        throw error;
      }
    }

    return [returnData];
  }
}

Key Programmatic Helpers

UI Property Types

Dynamic Options (Load from API)

{
  displayName: 'Channel',
  name: 'channelId',
  type: 'options',
  typeOptions: { loadOptionsMethod: 'getChannels' },
  default: '',
}

// In the node class:
methods = {
  loadOptions: {
    async getChannels(this: ILoadOptionsFunctions) {
      const credentials = await this.getCredentials('myServiceApi');
      const channels = await myServiceApiRequest.call(this, 'GET', '/channels');
      return channels.map((c: any) => ({ name: c.name, value: c.id }));
    },
  },
};

Codex File (.node.json)

{
  "node": "n8n-nodes-myservice.myService",
  "nodeVersion": "1.0",
  "codexVersion": "1.0",
  "categories": ["Miscellaneous"],
  "resources": {
    "credentialDocumentation": [{ "url": "" }],
    "primaryDocumentation": [{ "url": "" }]
  }
}

The node field format is <package-name>.<node-internal-name>.

Error Handling

Two Error Classes

// In GenericFunctions.ts — wrap API errors:
throw new NodeApiError(this.getNode(), error as JsonObject);

// In execute() — wrap logic errors:
throw new NodeOperationError(this.getNode(), 'Unsupported operation', { itemIndex: i });

continueOnFail Pattern (ALWAYS use in execute loops)

See the programmatic style example above for the full pattern. The key structure:

1. Wrap each item's processing in try/catch
2. On catch: if this.continueOnFail(), push error data and continue
3. Otherwise, re-throw the error

Naming Conventions

Versioning Nodes

When making breaking changes, version the node instead of modifying in place:

import { INodeTypeBaseDescription, INodeTypeDescription, VersionedNodeType } from 'n8n-workflow';

export class MyService extends VersionedNodeType {
  constructor() {
    const baseDescription: INodeTypeBaseDescription = {
      displayName: 'My Service',
      name: 'myService',
      icon: 'file:myservice.svg',
      group: ['transform'],
      defaultVersion: 2,
      description: 'Interact with My Service',
    };
    const nodeVersions: IVersionedNodeType['nodeVersions'] = {
      1: new MyServiceV1(baseDescription),
      2: new MyServiceV2(baseDescription),
    };
    super(nodeVersions, baseDescription);
  }
}

Each version is a separate class with its own full INodeTypeDescription. Place in V1/ and V2/ subdirectories.

Testing & Publishing

Local Testing

# Build the node package
npm run build

# Link it into your n8n installation
npm link
cd ~/.n8n
npm link n8n-nodes-myservice

# Restart n8n — your node appears in the editor
n8n start

Publishing to npm

npm login
npm publish

After publishing, users install via: Settings → Community Nodes → Install → n8n-nodes-myservice

Ensure your package.json has:

• "n8n" object with nodes and credentials arrays pointing to dist/ files
• Correct main and files fields
• "keywords": ["n8n-community-node-package"]

Best Practices

Do:

• Use noDataExpression: true on resource/operation selectors
• Include action on every operation option
• Use constructExecutionMetaData with itemData for proper item linking
• Implement continueOnFail() in every execute loop
• Create GenericFunctions.ts for shared API request helpers
• Use NodeConnectionType.Main instead of string 'main'
• Use typeOptions: { password: true } for secret fields in credentials
• Use returnAll/limit pair for list operations

Don't:

• Modify v1 when adding features — create v2 instead
• Forget the codex .node.json file
• Use inputs other than [] for trigger nodes
• Hard-code API base URLs in execute — use credentials or requestDefaults
• Skip error wrapping — always use NodeApiError/NodeOperationError
• Create large monolithic node files — split descriptions into separate files per resource

Troubleshooting

Quick reference for common issues. For the full catalog of 16+ errors with fixes, see references/COMMON_MISTAKES.md.

Node not appearing in editor

1. Check package.json → n8n.nodes paths point to dist/ (not source)
2. Rebuild: npm run build
3. Re-link if using npm link and restart n8n

"Cannot find credential"

• Verify the name in your credential class matches the name in the node's description.credentials array (case-sensitive)
• Ensure credential file is listed in package.json → n8n.credentials

displayOptions not working

• Resource/operation value strings must match exactly (case-sensitive) between the selector and displayOptions.show

Empty response data

• For declarative nodes: verify postReceive → rootProperty extracts the correct JSON path from the API response

Item linking broken in output

• Add constructExecutionMetaData with { itemData: { item: i } } wrapping every returnJsonArray call

Related Files

• references/CREDENTIAL_PATTERNS.md — API key, OAuth2, and custom auth patterns
• references/TRIGGER_PATTERNS.md — Webhook, poll, and event trigger implementations
• references/EXAMPLES.md — Complete working node examples and helper patterns
• references/COMMON_MISTAKES.md — Error catalog with fixes