n8n Custom Node Development Guide

This guide explains how to create, build, and test a custom n8n node locally.

Prerequisites
Node Project Structure
Build and Link the Node Locally
Install Node in Local n8n Instance
Start n8n and Test
Updating Your Node
Troubleshooting
References

1. Prerequisites

Node.js installed (preferably using nvm)
n8n installed globally:
```
npm install -g n8n
```
A separate folder for your custom node, e.g.:
```
~/Desktop/project/n8n-nodes-starter
```

2. Node Project Structure

Your node project should have the following structure:

n8n-nodes-starter/
├── credentials/
│   └── EventHub.credentials.ts
├── nodes/
│   └── EventHub.node.ts
├── package.json
├── tsconfig.json
├── gulpfile.js
└── README.md

Example package.json:

{
    "name": "n8n-nodes-eventhub",
    "version": "0.1.0",
    "main": "dist/index.js",
    "scripts": {
        "build": "tsc && gulp build:icons"
    }
}

3. Build and Link the Node Locally

Navigate to your node folder:

cd ~/Desktop/project/n8n-nodes-starter

Build the node:

npm run build

This compiles TypeScript to dist/ and builds icons.

Create a global symlink for the node:

npm link

4. Install Node in Local n8n Instance

Create a custom folder for n8n (if it doesn’t exist):

mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y

Link your node into n8n:

npm link n8n-nodes-eventhub

Note: Ensure the name matches the name field in your node's package.json.

5. Start n8n and Test

Start n8n:

n8n start

Open n8n in your browser (default: http://localhost:5678).

Search for your node by its node class name (e.g., EventHub), not the package name.

6. Updating Your Node

After making changes, rebuild the node:

cd ~/Desktop/project/n8n-nodes-starter
npm run build

Restart n8n:

n8n start

7. Troubleshooting

Error	Solution
`TypeError: require(...).EventHub is not a constructor`	Ensure the class exported from credentials or node matches the import name exactly. Example: `typescript<br>export class EventHub implements INodeType { ... }<br>`
`E404` when linking	Do not run `npm link <node>` in the node source folder. Instead, run `npm link` in the source folder and `npm link <node-package-name>` in `~/.n8n/custom`.

8. References

Written by A.M. Rinas