Prerequisites

Before you begin, ensure you have the following installed on your machine:

  • Node.js and npm: For developing and building the custom node.
  • TypeScript: As custom nodes are written in TypeScript.
  • Docker and Docker Compose: For running n8n in a containerized environment.
  • Basic Knowledge of JavaScript/TypeScript and Docker: Understanding of these technologies will help you follow along.

Project Setup

Create a Project Directory: Start by creating a new directory for your project.

mkdir n8n-custom-node
cd n8n-custom-node

Creating the Custom Node

1. Initialize the Node Project

We’ll create a new Node.js project for our custom node.

mkdir custom-nodes
cd custom-nodes
npm init -y

This will create a package.json file in the custom-nodes directory.

2. Create the Node Files

Create the following files in the custom-nodes directory:

  • MyCustomNode.node.ts: The main TypeScript file for your custom node.
  • tsconfig.json: TypeScript configuration file.
  • index.ts: Entry point to export your node.
touch MyCustomNode.node.ts tsconfig.json index.ts

3. Write the Node Code

tsconfig.json

Configure the TypeScript compiler options.

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES2019",
    "lib": ["es2019"],
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["MyCustomNode.node.ts"],
  "exclude": ["node_modules"]
}

package.json

Add the necessary dependencies and scripts.

{
  "name": "my-custom-node",
  "version": "1.0.0",
  "description": "A custom node for n8n",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc"
  },
  "devDependencies": {
    "@types/node": "^14.14.37",
    "n8n-workflow": "^0.128.0",
    "typescript": "^4.2.4"
  },
  "dependencies": {}
}

Install the dependencies:

npm install

MyCustomNode.node.ts

Write a simple custom node that, for example, reverses a string input.

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

export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'My Custom Node',
    name: 'myCustomNode',
    group: ['transform'],
    version: 1,
    description: 'A custom node that reverses a string',
    defaults: {
      name: 'My Custom Node',
      color: '#1F8EB2',
    },
    inputs: ['main'],
    outputs: ['main'],
    properties: [
      {
        displayName: 'String to Reverse',
        name: 'stringToReverse',
        type: 'string',
        default: '',
        placeholder: 'Enter a string',
        description: 'The string to reverse',
      },
    ],
  };

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

    const stringToReverse = this.getNodeParameter('stringToReverse', 0) as string;
    const reversedString = stringToReverse.split('').reverse().join('');

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

    return this.prepareOutputData(returnData);
  }
}

index.ts

Export your custom node.

import { INodeType } from 'n8n-workflow';
import { MyCustomNode } from './MyCustomNode.node';

export const nodeTypes:{ INodeType[] = [
  new MyCustomNode(),
]MyCustomNode };

4. Compile the TypeScript Code

Run the build script to compile your TypeScript code into JavaScript.

npm run build

This will generate a dist directory containing the compiled JavaScript files.

Docker Setup

To run n8n with your custom node, we’ll set up a Docker environment.

1. Create a Dockerfile

In the root of your project (n8n-custom-node), create a Dockerfile.

touch Dockerfile

Add the following content:

FROM n8nio/n8n:latest

USER root

# Copy the custom nodes folder
COPY ./custom_nodes /home/node/.n8n/custom/node_modules/custom_nodes

# Switch back to the node user
USER node

# Set the working directory
WORKDIR /home/node

# Use the default entrypoint and CMD from the base image

2. Create a Docker Compose File

Create a docker-compose.yml file in the root directory.

touch docker-compose.yml

Add the following content, using environment variables similar to those from your example setup:

volumes:
  n8n_storage:
  postgres_storage:

networks:
  n8n-local:

services:
  postgres:
    image: postgres:latest
    networks: ['n8n-local']
    restart: unless-stopped
    ports:
      - 5432:5432
    environment:
      - POSTGRES_USER
      - POSTGRES_PASSWORD
      - POSTGRES_DB
    volumes:
      - postgres_storage:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    build:
      context: .
      dockerfile: Dockerfile
    image: n8nio/n8n:latest
    networks: ['n8n-local']
    container_name: n8n
    restart: unless-stopped
    ports:
      - 5678:5678
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_AI_OPENAI_API_KEY=${N8N_AI_OPENAI_API_KEY}
      - N8N_AI_OPENAI_MODEL=gpt-4o-2024-08-06
      - N8N_HOST=${N8N_HOST}
      - NODE_FUNCTION_ALLOW_BUILTIN=*
      - NODE_FUNCTION_ALLOW_EXTERNAL=*
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom/node_modules/custom_nodes
    links:
      - postgres
    volumes:
      - n8n_storage:/home/node/.n8n
      - ./shared:/data/shared
      - ./custom_nodes:/home/node/.n8n/custom/node_modules/custom_nodes
    depends_on:
      postgres:
        condition: service_healthy

Running n8n with Your Custom Node

Check n8n Logs (optional):

docker-compose logs -f n8n

This can help you verify that n8n started correctly and that your custom node was loaded.

Verify the Container is Running

docker-compose ps

You should see the n8n service listed and running.

Run the Docker Container

docker-compose up -d

This will start the n8n service in detached mode.

Build the Docker ImageIn your project root, run:

docker-compose build

This will build the Docker image, including your custom node.

Create a .env File: In the root of your project, create a .env file to store your environment variables.

POSTGRES_USER=your_postgres_user
POSTGRES_PASSWORD=your_postgres_password
N8N_ENCRYPTION_KEY=your_encryption_key
N8N_AI_OPENAI_API_KEY=your_openai_api_key
N8N_HOST=your_n8n_host

Using Your Custom Node in n8n

  1. Access n8nOpen your web browser and navigate to http://localhost:5678.
  2. Create a New WorkflowClick on “New Workflow” in the top-right corner.
  3. Add Your Custom Node
    • Click on the “+” button to add a new node.
    • Search for “My Custom Node”.
    • Add it to your workflow.
  4. Configure the Node
    • String to Reverse: Enter any string you wish to reverse.
  5. Execute the Workflow
    • Click on “Execute Workflow” to run the workflow.
    • After execution, click on the node to see the output.
    • You should see the reversed string in the output.

Conclusion

Congratulations! You’ve successfully created a custom node for n8n, set up a Docker environment, and integrated your custom node into n8n using Docker Compose. This guide provides a foundation for you to develop more complex custom nodes tailored to your specific needs.

Additional Resources

Tips and Best Practices

  • Node Development: When developing custom nodes, it’s helpful to refer to the n8n source code and existing nodes for examples.
  • Testing: Regularly test your node during development to catch any issues early.
  • Version Control: Use Git or another version control system to manage your code changes.
  • Documentation: Comment your code and provide clear descriptions in your node’s description object to make it easier to use and maintain.

By following this guide, you should now have the skills to create and integrate custom nodes into n8n using Docker. This setup is ideal for development and testing purposes. For production environments, consider additional security measures and optimizations.

If you have any questions or run into issues, the n8n community is a great place to seek help and share your experiences.

Happy automating!