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

Building a custom n8n node lets you extend workflows with functionality that isn’t available out of the box. This guide walks through creating, developing, and publishing a custom node package — from setting up the repository to releasing it on npm. Follow the steps below and you’ll have a reusable node you can attach to any workflow.

Prerequisites

• GitHub account to host your project repository.
• Node.js v22 or higher (check with node -v).
• npm (check with npm -v).
• A code editor (VS Code recommended) and a terminal.

Step 1 — Create a GitHub repository and clone it locally

Create a new repository on GitHub (example name: test-n8n-node). Choose a license (MIT is common) and set the repo to public or private depending on your needs.

Clone the repository to your local machine:

git clone https://github.com/your-username/test-n8n-node.git
cd test-n8n-node

Step 2 — Scaffold a new n8n node using the CLI

The fastest way to get started is the n8n node scaffolding CLI. From your project folder run:

npm create @n8n/node

The CLI will prompt you for a few values. Typical prompts and recommended answers:

• Package name: a unique npm package name (the default will be something like @n8n/nodes-yourapp)
• Type of node: choose the appropriate template (for example, a REST/http-based node)
• Accept the default folder structure unless you have a reason to change it

The scaffolder generates:

• A nodes folder with the node implementation (description, UI definition, and the execute method that runs during workflow execution)
• A credentials folder for secure API key/token handling if your node needs authentication
• A package.json with scripts and metadata for building, testing, and publishing

Step 3 — Set up local development

Before editing code, add a .gitignore so you do not push node modules to GitHub. Create a file named .gitignore in the project root with at least:

node_modules/
dist/
.env

Install dependencies and start the local development environment:

npm install
npm run dev

npm run dev will build the TypeScript project and start a local editor/server where you can test and preview the node. Open the provided local port in your browser to access the editor and the node testing interface.

Edit your node files inside the generated folder. The main node file will contain a description section, parameter definitions for the UI, and an execute method where the runtime logic lives.

Step 4 — Build and publish your node

When your node is ready, build it:

npm run build

To publish to npm:

npm run release

Notes about publishing:

• The release process may run linting. Fix any lint or type errors before publishing.
• Choose a unique package name to avoid conflicts on npm.
• If your package should be public, ensure package.json is configured accordingly; private packages require different access handling.

After publishing, others can install your custom n8n node package and use it in their workflows.

Troubleshooting and tips

• Node or npm version issues: If node -v shows a version below 22, update Node (nvm is useful for switching versions).
• Lint errors: The release pipeline commonly fails on lint/type errors. Run linters locally and fix reported issues before release.
• Keep the repo lightweight: Never commit node_modules. Use .gitignore so collaborators run npm install themselves.
• Credentials: Store API keys and tokens securely—keep them out of source control and use the generated credentials structure to manage authentication safely.
• Testing: Use the dev server and n8n’s test editor to exercise your node thoroughly before publishing.

Checklist before publishing

• Project builds successfully with npm run build.
• No lint or type errors remain.
• .gitignore contains node_modules/ and other sensitive files.
• Package name is unique on npm and package.json metadata is correct.
• Credentials handling is secure and not committed to the repository.
• Repository pushed to GitHub with a clear README explaining usage and configuration.

Final notes

Creating a custom n8n node is a powerful way to extend automation capabilities and integrate niche APIs or custom logic into workflows. The scaffolded project provides the structure you need; focus your work on the node's execute logic, parameter definitions, and secure credential handling. Once you're comfortable with the dev flow, publishing and sharing nodes becomes straightforward.

Try building a simple HTTP-based node first, verify it works locally, then iterate and add more advanced behavior. Keep your package small, documented, and well-tested before publishing.