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

Build a reusable n8n node from scratch, publish it to npm, and use it across any workflow. This guide walks through the practical steps—set up a repository, scaffold the node with the n8n CLI, understand the generated files, run the local editor, build, and publish. Follow the checklist and troubleshooting tips to avoid common pitfalls.

Quick overview

• Create a GitHub repository for your node project
• Clone the repo locally and scaffold using the n8n CLI
• Understand the generated folders: nodes, credentials, package.json
• Run the local editor for development
• Build and publish to npm (fix lint errors first)

Prerequisites

• Node.js version 22 or higher (Node 24+ recommended)
• npm installed
• GitHub account and basic familiarity with git

Step 1 — Create the GitHub repository

Create a new repository (for example, test-any-node). Choose the MIT license if you want to make the code permissive. Make it public or private based on your needs.

Step 2 — Clone the repo and open your editor

Clone the repo to your machine and open it in your code editor before scaffolding the node.

git clone https://github.com/your-username/test-any-node.git
cd test-any-node
code .  # or open in your preferred editor

Step 3 — Check Node and npm versions

Confirm your runtime versions. If Node is lower than 22, update it.

node -v
npm -v

Note: Node 22+ is required for the modern n8n CLI templates and TypeScript build chain.

Step 4 — Scaffold a new n8n node project

Use the n8n create CLI to scaffold a new node package. This creates the node logic, credentials hooks, and a package.json with scripts for building and testing.

npm create @n8n/node

The CLI prompts for several values:

• Package name — typically something like n8n-nodes-yourname
• Node type — choose based on your API (HTTP, trigger, etc.)
• Template — pick a template (for example, GitHub issues API) or a minimal template if you prefer

When complete, the CLI initializes a project folder with a sample node and credentials file. It also generates a package.json and TypeScript configuration.

What the scaffold creates

• nodes/ — your node implementation, UI definition, and execute logic
• credentials/ — files to securely define API auth and tokens
• package.json — scripts and metadata (build, dev, release)
• TypeScript build config and sample tests

Step 5 — Add a .gitignore

Ensure you do not commit node modules. Create a .gitignore in your project root with at least the following:

node_modules/
dist/
.env

Step 6 — Install dependencies and run the local editor

Install packages, then run the dev server that serves the local n8n node editor/preview.

npm install
npm run dev

After the TypeScript build completes, the project will start a local server and expose an editor UI on a local port. Use that editor to preview and test the node in a real workflow environment.

Step 7 — Develop your node

Edit the files in nodes/ to implement your node’s logic and UI. The main file will typically export a class with a description (inputs, outputs, properties) and an execute method (the action that runs during workflow execution).

Tip: Keep the credentials logic isolated in credentials/ so the node can securely request API keys and tokens.

Step 8 — Build the project

When your code is ready, build the TypeScript project for release:

npm run build

Step 9 — Publish to npm

The scaffold contains a release script that bundles and publishes the package to npm. Before publishing, the release process runs linters and checks that must pass.

npm run release

If the linter reports errors, fix them, bump the package version if necessary, and retry the release. Once successful, your node package will be available on npm and can be installed into other n8n instances.

Troubleshooting and common gotchas

• Lint errors block release — run the linter locally, fix reported issues, and ensure tests pass before publishing.
• Don’t commit node_modules — keep your repo lightweight and require consumers to run npm install.
• Credential storage — define credentials correctly so end-users can securely connect to external APIs.
• Versioning — bump your package.json version for each release to avoid npm publish conflicts.
• Node version — if build or CLI commands fail, confirm you are running Node 22+ and update if needed.

Release checklist

1. Confirm Node and npm versions (Node >= 22)
2. Run npm install and confirm the project builds locally
3. Run the dev server and validate the node in the editor
4. Fix lint and test issues
5. Update package.json version
6. Run npm run release to publish

Final tips

• Start with a template that resembles the API pattern you need (REST, webhook, trigger).
• Write clear property descriptions in the node's UI so other users know what each field does.
• Include tests if possible; they help avoid regressions when users depend on your node.

With these steps you can create a custom n8n node, test it locally, and publish it for reuse. The n8n CLI does the heavy lifting of scaffolding, letting you focus on implementing the API logic and user interface for the node.