How to Build and Publish Your Own n8n Community Node

An n8n community node is an npm package that adds one or more nodes to n8n (see What Are n8n Community Nodes? for the user side). If a service you use has no node yet, you can build one yourself, test it in a local n8n, publish it to npm so anyone can install it, and optionally submit it to n8n for verification so it also works on n8n Cloud. This guide follows the official n8n documentation on creating nodes step by step.

What you need before you start

n8n’s docs assume some familiarity with JavaScript and TypeScript, managing your own development environment with git, knowledge of npm including publishing packages, and a good understanding of n8n’s data structures and item linking. The tools:

• Node.js and npm, Node 22.22.0 or later.
• The n8n-node CLI (@n8n/node-cli), n8n’s official tool to create, build, lint, run and release community nodes. It includes n8n for local development, so you don’t need a separate n8n install. It is required if you want your node verified.
• git.
• n8n recommends VS Code with the ESLint, EditorConfig and Prettier extensions, so you see the n8n node linter’s warnings while you type.

Step 1: Pick declarative or programmatic style

n8n has two ways to write a node. Its docs say to build in the declarative style unless you have a reason not to: it uses a JSON-based syntax, needs no execute() method, is simpler with less risk of bugs, is more future-proof and is designed for REST APIs.

Use the programmatic style only when your node is one of these:

• A trigger node. The declarative style doesn’t support triggers.
• A node that isn’t REST-based, for example one that calls a GraphQL API or uses external dependencies.
• A node that has to transform data beyond what routing handles (routing.request.preSend and routing.output.postReceive).
• A node that needs feature-based versioning in code (this.isNodeFeatureEnabled()).

One package can mix both, for example a declarative action node and a programmatic trigger node for the same service.

Step 2: Create the project with n8n-node

You can create a project without installing anything globally:

npm create @n8n/node@latest

Or install the CLI once and use n8n-node new:

npm install --global @n8n/node-cli
n8n-node --version
n8n-node new

The interactive prompt asks:

• What is your node called? The name must be n8n-nodes-<name> or @<your-org>/n8n-nodes-<name>. It becomes the folder, the npm package name and the node name.
• What kind of node are you building? HTTP API gives a declarative node, which n8n describes as designed for faster approval for n8n Cloud. Other gives a programmatic node; pick it for triggers.
• Which template? For HTTP API, GitHub Issues API is a demo with several operations and credentials, and Start from scratch is blank. Start from scratch then asks for the API base URL and the authentication type: API Key, Bearer Token, OAuth2, Basic Auth, Custom or None.

To skip the prompts, pass the name and template directly. The templates are declarative/github-issues, declarative/custom and programmatic/example:

npm create @n8n/node@latest n8n-nodes-mynode -- --template declarative/custom

The tool creates the project folder and installs its dependencies (add --skip-install to skip that).

Step 3: Build, lint and run it in n8n

Inside the project folder, the CLI gives you these commands (each also works as an npm script):

After npm run dev, open localhost:5678, sign in, open a workflow and search for your node in the nodes panel. From n8n 3.0 the dev command runs that n8n in a container, so you need Docker or Podman. If you’d rather use an n8n you run yourself, start it with N8N_DEV_RELOAD=true and run n8n-node dev --external-n8n.

The linter is @n8n/eslint-plugin-community-nodes. It checks node files (*.node.ts), credential files (*.credentials.ts) and package.json, and runs automatically after installing dependencies and before publishing. n8n asks you not to edit the eslint.config.mjs file the tool generates. If you must make an exception, disable a rule only for a line where you have good reason to.

Step 4: Check the community node standards

To be installable as a community node, the package has to follow n8n’s standards. A project made with n8n-node already does, but check:

• The package name starts with n8n-nodes- or @<scope>/n8n-nodes-.
• n8n-community-node-package is in the package keywords. This is the keyword n8n’s Browse button searches npm for.
• Your nodes and credentials are listed in package.json under the n8n attribute.
• The linter passes and the node works when you test it locally.

Step 5: Publish to npm

The simplest path is the CLI’s release command. Log in to npm first, because without it the tool can’t publish:

npm login
npm run release

release uses release-it to build the node, run the lint checks, update the changelog, create git tags, create a GitHub release and publish the package to npm.

If you plan to submit the node for verification, publish it from GitHub Actions with an npm provenance statement instead. From May 1, 2026, n8n doesn’t accept verified nodes published from a local machine. Provenance lets anyone check which workflow, repository and commit built the package.

• New projects: the npm create @n8n/node scaffold already includes a publish.yml workflow. Run npm run release locally to bump the version, commit, tag and push; the push triggers the workflow, which publishes to npm.
• Existing projects: add the publish workflow from n8n-nodes-starter as .github/workflows/publish.yml, and make sure @n8n/node-cli 0.23.0 or later is a devDependency (npm list @n8n/node-cli).
• One-time npm setup: on npmjs.com open the package settings, go to Publish access > Trusted Publishers, select Add a publisher, choose GitHub Actions and enter the repository owner, repository name and the workflow file name publish.yml. A granular access token stored as the NPM_TOKEN Actions secret also works.

Once your package is on npm, self-hosted n8n users can install it by name from Settings > Community Nodes. New npm packages with n8n-nodes in the name also appear on communitynodes.com after our daily npm sync, on the new community nodes page.

Step 6: Submit it for verification (optional)

Verified nodes show up in the nodes panel for every n8n user with verified community nodes enabled, on self-hosted n8n and on n8n Cloud. n8n’s docs call this the only way to use custom nodes on Cloud. Before you submit, check the verification guidelines:

• Start from the n8n-node scaffold (strongly suggested) and pass all automated checks, including npx @n8n/scan-community-package <your-package>.
• One third-party service per package, not a duplicate of an existing n8n node, and not a logic or flow control node.
• No run-time dependencies, and no access to environment variables or the file system.
• A public GitHub repository that matches the npm package and author, and an MIT license.
• A README with usage instructions, example workflows and authentication details; interface and docs in English only.
• TypeScript, n8n’s node guidelines and UX guidelines.
• Published from GitHub Actions with provenance (step 5).

Then sign up or log in to the n8n Creator Portal and submit the node. n8n reserves the right to reject nodes that compete with its paid features, especially enterprise functionality. Our explainer Verified vs Unverified n8n Community Nodes covers what verification means for users.

Private nodes: use it without publishing

For a node meant only for your company, you don’t have to publish to npm. n8n documents two ways:

• Docker: build a custom n8n image. Compile the node (npm run build) and copy the node and credential folders from dist into the container’s ~/.n8n/custom/ directory as part of the image. n8n’s guide walks through the Dockerfile.
• Global npm install of n8n: install your node inside n8n, and n8n finds and loads it automatically.

The N8N_CUSTOM_EXTENSIONS environment variable can also point n8n at directories that contain your custom nodes. Private nodes can’t be used on n8n Cloud.

Before your first release: learn from existing nodes

n8n points node authors to its own built-in nodes for patterns. It also helps to see what already exists for your service: check our hubs for OpenAI, MCP, WhatsApp, Telegram or Apify, and the most downloaded packages on the homepage. Users install nodes the way our guide How to Install n8n Community Nodes describes, which is worth reading from the other side before you write your README.

FAQ

What should I name my n8n community node package?

n8n-nodes-<name> or @<your-org>/n8n-nodes-<name>, and add the keyword n8n-community-node-package.

Do I need to install n8n to develop a node?

No. The n8n-node CLI includes n8n for local development. npm run dev starts it with your node loaded (from n8n 3.0 in a Docker or Podman container).

Declarative or programmatic?

Declarative by default. Programmatic for triggers, non-REST APIs such as GraphQL, nodes with external dependencies, heavy data transformation or feature-based versioning.

Can I use npm packages inside my node?

In an unverified node, yes. Verified nodes can’t have run-time dependencies.

How do I get my node onto n8n Cloud?

Get it verified: publish from GitHub Actions with provenance, meet the verification guidelines and submit it in the n8n Creator Portal.

How do I publish a new version?

Run npm run release. With the GitHub Actions setup, that bumps the version, tags and pushes, and the workflow publishes to npm.