n8n Custom Nodes: Do You Need One, and Which Kind?

This is the written version of Part 1 of Build your own n8n node, a ten-part series that takes one API from an empty folder to a verified n8n community node. There's no code to write in this part. It answers the question most tutorials skip: should you build a node at all, and if so, which kind?

The email that starts it

If your product has an API, you've probably had this email: "Do you support n8n?" Probably more than once.

The usual reply is "Not yet, but you can use the HTTP Request node." That's true, and it means the customer has to read your API docs and build every request themselves. Some will. A lot of them won't.

What an n8n node is

n8n's HTTP Request node can talk to any API there is. To use it with yours, a person needs to:

• know your API exists and read its docs
• find the right endpoint
• work out how authentication works
• set the method, URL, headers and body by hand

A proper node asks different questions. Open n8n's Slack node and you pick a resource, an operation and a channel. There's no URL and no header anywhere. The person using it might not know what an API is.

That's all a node is: your API, with the hard part done ahead of time. The same requests go out underneath. You've done the thinking so your users don't have to.

Four options, from least work to most

Option	Who can use it	What you build
HTTP Request node	Anyone, today	Nothing, or a docs page and a template workflow
Private node	Only the n8n instances you install it on	A node you keep to yourself
Community node	Anyone who self-hosts n8n	A node published to npm
Verified community node	Everyone, including n8n Cloud	A published node that n8n has reviewed

1. Do nothing. If two people a year ask about n8n, stop here. A short docs page and a workflow template people can copy will help them more than a node nobody maintains.

2. A private node. You build it, and it lives only on your own n8n. It's a good fit for a team's internal workflows. Your customers never see it.

3. A community node. You publish it to npm, and anyone running their own n8n can install it by its package name. This is the one most API owners are after.

4. A verified community node. The same node after n8n has reviewed it. Users find it by searching n8n's nodes panel, and it works on n8n Cloud, where unverified community nodes can't be installed at all. This series ends here.

If you think you'll want the badge one day, plan for it from the start. Some of the rules, like how the package is published and what it may depend on, are much easier to follow on day one than to fix later. The verification guide has the full list.

Declarative or programmatic

There are two ways to build a node, and it's worth deciding before you write anything.

Declarative. You describe each request, and n8n sends it for you. Creating a contact is a POST to /contacts, and the Email field goes in the body:

{
  name: 'Create',
  value: 'create',
  action: 'Create contact',
  routing: {
    request: { method: 'POST', url: '/contacts' },
  },
}

Programmatic. You write an execute() function that makes the calls and handles what comes back:

async execute(this: IExecuteFunctions) {
  const items = this.getInputData();
  // make the requests yourself, item by item
}

Declarative means less code and less to break, and it's what n8n's docs recommend for new nodes. Programmatic can do anything, and you maintain all of it.

So start declarative, and switch on the day declarative can't do what you need. n8n's docs name the usual reasons: a trigger node, an API that isn't REST (GraphQL, for example), or an operation that has to transform data or chain several requests together. That day comes for most nodes that grow, and Part 5 shows the exact moment.

What's inside a node package

Less than you'd expect. A community node is an npm package, and four parts of it are yours:

n8n-nodes-acme-crm/
├── nodes/AcmeCrm/AcmeCrm.node.ts          the node: its name, fields and operations
├── nodes/AcmeCrm/acme.svg                 the icon
├── credentials/AcmeCrmApi.credentials.ts  how a user logs in
└── package.json                           tells n8n there's a node in here

Acme CRM is the example used across the whole series: an invented CRM with contacts and deals. Swap in your own API as you follow along.

Everything else in a generated project is configuration for TypeScript and the linter, which you'll rarely open. The rest of the series is about filling those four parts in properly.

The rest of the series

All ten parts are in the Build your own n8n node playlist on YouTube, in order, and each one has a written guide like this one.

Next, in Part 2, we open an empty folder, and by the end your node is on the n8n canvas with your name on it.

One more thing. We build NativeShip, the tool this site is about. You give it your API's OpenAPI spec, and it generates the n8n node package, checks it with a build, and gets it ready to publish under your own name. If you'd rather build it by hand, good: that's what the next nine parts are for.