Just recently I wanted to develop a community node for n8n, but after reading the documentation and spending hours on trying different approaches, I still was not able to set up a working development environment.
On my journey I actually stumbled upon many users who struggled with the same issues.
Why is that? npm has been replaced with pnpm in the nodes starter template and the official documentation has not been updated accordingly – just yet.
In the end I found two solutions:
- Running locally by modifying the starter template – check out this video by @benyoung. He did an amazing job in explaining that and even more about the node development in detail!
- Running in docker by mounting the dist folder – based on an article from @hubschrauber, with a tiny modification
While both solutions work, in my opinion the second one is easier to setup and use. Let me share some step-by-step instructions.
Step 1: Generate repository and set it up locally
Follow the official instructions mentioned here except for installing n8n (prerequisites section) and instead of point 8 do the following steps.
Step 2: Setup Docker and mount the custom node
Create a separate folder somewhere named n8n-dev or similar and create a compose.yaml file similar to this one inside (make sure to mount the dist folder of the cloned repo as shown).
services:
n8n:
image: n8nio/n8n:latest
container_name: n8n-dev
restart: unless-stopped
ports:
- 5678:5678
volumes:
- /etc/localtime:/etc/localtime:ro
- ./data:/home/node/.n8n
- /<path-to-cloned-repo>/dist:/home/node/.n8n/custom/node_modules/<repo-name> # one line per package
# Example: /Users/mario/Development/n8n-nodes-test/dist:/home/node/.n8n/custom/node_modules/n8n-nodes-test
Start the container with: docker compose up -d
Step 3: Load changes into dev environment
Initially and after making changes in the codebase, simply run this command within the repo folder to load the updated node into the n8n dev environment: pnpm build && docker restart n8n-dev && docker logs n8n-test -f
It rebuilds the package, restarts the Docker container and also shows the container logs, which can be exited anytime using Ctrl+C
After a successful build the logs should output the URL of the n8n instance (should be http://localhost:5678/), otherwise the error shows up.
Now you should be able to test your custom node after logging into the n8n instance.
Step 4: Publish the community node
Continue with the official instructions at point 9 to add the final touches and publish the package to npm.
This solution has been tested at this state of the template’s codebase: GitHub - n8n-io/n8n-nodes-starter at 74b954cc9a3ed944011de248bb341224cf7cfdff