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.preSendand the API response withrouting.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@featureindisplayOptions. 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.
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:
Related resources
Last updated
Was this helpful?