Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Choose a node building style

n8n has two node-building styles, declarative and programmatic. Build your node in the declarative style. It's the default for new nodes.

The declarative style:

  • Uses a JSON-based syntax, making it simpler to write, with less risk of introducing bugs.

  • Is more future-proof.

  • Supports integration with REST APIs.

  • Needs no execute() method, so there's less code to write and maintain.

If you're not sure which style your node needs, start declarative. The n8n-node tool scaffolds a declarative node for you, and Build a declarative-style node walks through a complete example.

When you need the programmatic style

The programmatic style is more verbose, and it puts your node's behavior in code that you have to maintain. Treat it as the exception. Use the programmatic style when your node is one of these:

  • A trigger node.

  • A node that isn't REST-based. This includes nodes that need to call a GraphQL API and nodes that use external dependencies.

  • A node that needs to transform data beyond what routing handles. The declarative style can change the request with routing.request.preSend and the API response with routing.output.postReceive. Use the programmatic style when your node needs to work on incoming items independently of a single API call.

  • A node that needs feature-based versioning to branch its behavior in code, using this.isNodeFeatureEnabled(). Declarative nodes can still use light versioning, and can read feature flags with @feature in displayOptions. Refer to Node versioning for more information on types of versioning.

If your node isn't on this list, build it in the declarative style.

Trigger nodes must use the programmatic style

The declarative style doesn't support trigger nodes. Build every trigger node in the programmatic style, even when the action node for the same service is declarative.

You can mix both styles in one node package. For example, a package submitted for verification can contain a declarative-style action node and a programmatic-style trigger node for the same service.

Data handling differences

The main difference between the declarative and programmatic styles is how they handle incoming data and build API requests. The programmatic style requires an execute() method, which reads incoming data and parameters, then builds a request. The declarative style handles this using the routing key in the operations object. Refer to Node base file for more information on node parameters and the execute() method.

Syntax differences

To understand the difference between the declarative and programmatic styles, compare the two code snippets below. This example creates a simplified version of the SendGrid integration, called "FriendGrid." The following code snippets aren't complete: they emphasize the differences in the node building styles.

FriendGrid calls a REST API and doesn't transform its input, so the declarative style is the right choice for it. In declarative style:

The same node in programmatic style needs an execute() method to read the parameters and build the request by hand:

Last updated

Was this helpful?