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

Creating a custom node for n8n lets you extend its automation power to any API or workflow you need. This guide walks through a simple, repeatable process: create a repository, scaffold a node with the n8n CLI, develop locally, build, and publish. Follow these steps to get a reusable node you can install or publish to npm.

Overview

The basic workflow:

1. Create a GitHub repository for your node project.
2. Clone the repo locally and scaffold the node using the n8n CLI.
3. Develop the node code and credential file.
4. Run the local editor and debug during development.
5. Build, fix lint issues, and publish the package.

Prerequisites

• Node version 22 or higher.
• npm installed (check your versions before starting).
• A GitHub account and basic familiarity with cloning/pushing repositories.

Quick commands to verify your environment

node --version
npm --version

1. Create a GitHub Repository

Start by creating a new repository on GitHub. Keep it simple for the tutorial—name it something like test-any-node and choose the MIT license. You can make it public or private depending on your needs.

2. Clone Locally and Open Your Editor

Clone the repository to your machine and open it in your preferred code editor.

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

3. Scaffold the Node with the n8n CLI

The fastest way to start is using the n8n node scaffolding tool. Run:

npm create @n8n/node

The CLI will prompt you for metadata such as package name, node type, and template. Accept the defaults or choose a template that matches your goal. For example, the GitHub Issues API template is useful if you plan to build integrations similar to GitHub.

What the CLI generates:

• A folder with your node source files that contains the node logic and UI definition (description and execute method).
• A credentials folder (if the template requires it) to securely manage API keys or tokens.
• A package.json with scripts for building and testing.

4. Add .gitignore

Always add a .gitignore so you don’t push node_modules. This keeps the repo lightweight and requires collaborators to run npm install locally.

# .gitignore
node_modules
dist
.env

5. Install Dependencies and Run the Local Editor

After scaffolding, install dependencies and run the development server. The package generated by the CLI includes helpful scripts.

npm install
npm run dev

When the build completes, a local editor becomes available at a specified port. Use that editor to preview the node definition, enter credentials, and debug the node during workflow execution.

6. Write Your Node Code

Open the scaffolded files and implement the logic for your node.

• Define the node description and properties that users will configure.
• Implement the execute method with API calls and response handling.
• Securely handle API keys using the generated credentials file.

7. Build and Fix Lint Errors

Before publishing, build the project and fix any lint or TypeScript errors the build process reports.

npm run build

If lint or compile errors appear, address them in your source files. The build must succeed before release.

8. Publish Your Node

Once the build is clean, you can release the package. The generated project usually includes a release script that packages and publishes to npm.

npm run release

Note: you will need proper npm authentication and a valid package name. Fix any remaining linting or metadata issues reported during release.

Tips and Troubleshooting

• Keep repo lightweight: Never commit node_modules—use .gitignore as shown above.
• Node version: If your node version is older than 22, update it to avoid build problems.
• Fix lint early: Lint errors often block publishing; run the linter locally and configure your editor to catch issues as you code.
• Credentials: Use the credential files generated by the scaffold to store API keys securely. Avoid committing secrets to source control.
• Testing locally: Use the local editor and the n8n runtime to test node behavior in workflows before releasing.

What You’ll End Up With

A reusable n8n node package that includes:

• Node logic and UI definition files
• Credential handling files
• Build and release scripts in package.json

Publish to npm for wide reuse or keep the package private and install it into your n8n instance for internal automations.

Final Notes

Creating a custom node for n8n is a powerful way to tailor automation to specific tools and APIs. The CLI scaffold takes care of the boilerplate so you can focus on implementing the integration logic. Build, test, fix linting, and publish when ready—then reuse the node across workflows.