How To Create a Custom Node in n8n (2026 Updated Tutorial)

Building a custom n8n node lets you extend workflows with tailored integrations and logic. This step-by-step guide walks through setting up a repository, scaffolding a node with the n8n CLI, running a local editor, building, and publishing your node to npm. Follow these practical steps and tips to get a reusable custom node that works across your n8n instances.

What you need before you start

• Node.js version 22 or higher
• npm (check your version with the commands below)
• A GitHub account and basic familiarity with cloning repositories
• A code editor (VS Code recommended)

Check your versions

node -v
npm -v

The process works smoothly with Node 22+; if your machine uses an older Node version, update it before continuing.

1. Create a GitHub repository

1. Create a new repository on GitHub. Name it something memorable such as test-n8n-node.
2. Choose a license (MIT is a simple, permissive choice) and set the repo to public or private based on your needs.
3. Clone the repository locally and open it in your editor.

2. Scaffold a new n8n node project with the CLI

The n8n project provides a CLI that scaffolds a node project quickly. Use the create command to generate the initial folder structure, node files, and credential templates.

Run the CLI

npm create @n8n/node

The CLI will prompt for a few values:

• Package name (a default such as @n8n/nodes-your-app will be suggested)
• Type of node and template to use (choose an appropriate template such as a GitHub Issues API example if you want a starting point)

The scaffold will create:

• A node folder containing the main logic and UI definition
• A credentials folder to hold secure credential templates (for API keys, tokens, etc.)
• A package.json with metadata and scripts for building and testing

3. Install dependencies and run the local editor

After scaffolding, install dependencies and start the development server. The project typically uses TypeScript and provides a local editor where you can test and preview the node UI.

npm install
npm run dev

When the build completes the CLI will show a local port where the editor is available. Open that URL in your browser to preview and interact with the node while you develop.

4. Write your node code

The scaffold sets up the basic file structure. The important parts are:

• Node file — defines the node description and the execute method that runs during workflow execution
• Credentials file — defines how to store and use API keys or tokens

Edit the node files to add inputs, outputs, UI properties, and the logic that communicates with the external API or performs the required actions. Keep changes small and test frequently using the local editor.

5. Add a .gitignore

Ensure you do not push node_modules to GitHub. At the root of the project create a .gitignore file and include:

node_modules/

This keeps the repository lean. Anyone who clones the repo will run npm install locally to restore dependencies.

6. Build and publish your node

When the code is ready, build the project and publish it to npm so it can be installed into other n8n instances.

npm run build
npm run release

Note: linters or package checks may report errors during the release step. Fix any lint or packaging errors before attempting to publish. Once npm run release completes successfully, your custom node will be available on npm.

Troubleshooting and tips

• Lint and test locally — run the build and any tests frequently to catch issues early.
• Credentials — use the credentials folder template to handle API keys securely; do not commit real secrets to the repository.
• Version control — keep the repo history clean and use meaningful commits so you can track changes to node logic and UI definitions.
• Keep dependencies up to date — update TypeScript and packages when necessary, but test compatibility with n8n versions.

Quick command summary

# Create and clone repo
# (on GitHub) create repository, then locally
git clone https://github.com/youruser/test-n8n-node.git
cd test-n8n-node

# Scaffold
npm create @n8n/node

# Install and develop
npm install
npm run dev

# Build and publish
npm run build
npm run release

Final notes

Creating a custom n8n node unlocks powerful integration and automation possibilities. Follow the scaffolding, test in the local editor, and publish once your node is stable. With a well-structured repository and secure credential handling, your custom node will be reusable and easy to maintain.