Node base file#
The node base file contains the core code of your node. All nodes must have a base file. The contents of this file are different depending on whether you're building a declarative-style or programmatic-style node. For guidance on which style to use, refer to Choose your node building approach.
This document gives short code snippets to help understand the code structure and concepts. For full walk-throughs of building a node, including real-world code examples, refer to Build a declarative-style node or Build a programmatic-style node.
You can also explore the n8n-nodes-starter and n8n's own nodes for a wider range of examples. The starter contains basic examples that you can build on. The n8n Mattermost node is a good example of a more complex programmatic-style node, including versioning.
Structure of the node base file#
The node base file follows this basic structure:
- Import statements
- Create a class for the node
- Within the node class, create a
description
object, which defines the node.
A programmatic-style node also has an execute()
method, which reads incoming data and parameters, then builds a request. The declarative style handles this using the routing
key in the properties
object, within descriptions
.
Outline structure for a declarative-style node#
This code snippet gives an outline of the node structure.
1 2 3 4 5 6 7 8 9 10 |
|
Outline structure for a programmatic-style node#
This code snippet gives an outline of the node structure.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Standard parameters#
These parameters are the same for all node types.
displayName#
String | Required
This is the name users see in the n8n GUI.
name#
String | Required
The internal name of the object. Used to reference it from other places in the node.
icon#
String | Required
Starts with file
. For example, icon: 'file:exampleNodeIcon.svg'
.
n8n recommends using an SVG for your node icon, but you can also use PNG. If using PNG, the icon resolution should be 60x60px. Node icons should have a square or near-square aspect ratio.
Don't reference Font Awesome
If you want to use a Font Awesome icon in your node, download and embed the image.
group#
Array of strings | Required
Tells n8n how the node behaves when the workflow runs. Options are:
trigger
: node waits for a trigger.schedule
: node waits for a timer to expire.input
,output
,transform
: these currently have no effect.- An empty array,
[]
. Use this as the default option if you don't needtrigger
orschedule
.
description#
String | Required
A short description of the node. n8n uses this in the GUI.
defaults#
Object | Required
Contains essential brand and name settings.
The object can include:
name
: String. Used as the node name on the canvas if thedisplayName
is too long.color
: String. Hex color code. Provide the brand color of the integration for use in n8n.
inputs#
Array of strings | Required
Names the input connectors. Controls the number of connectors the node has on the input side. If you need only one connector, us input: ['main']
.
outputs#
Array of strings | Required
Names the output connectors. Controls the number of connectors the node has on the output side. If you need only one connector, us output: ['main']
.
credentials#
Array of objects | Required
This parameter tells n8n the credential options. Each object defines an authentication type.
The object must include:
name
: the credential name. Must match thename
property in the credential file. For example,name: 'asanaApi'
inAsana.node.ts
links toname = 'asanaApi'
inAsanaApi.credential.ts
.required
: Boolean. Specify whether authentication is required to use this node.
requestDefaults#
Object | Required
Set up the basic information for the API calls the node makes.
This object must include:
baseURL
: The API base URL.
You can also add:
headers
: an object describing the API call headers, such as content type.url
: string. Appended to thebaseURL
. You can usually leave this out. It's more common to provide this in theoperations
.
properties#
Array of objects | Required
This contains the resource and operations objects that define node behaviors, as well as objects to set up mandatory and optional fields that can receive user input.
Resource objects#
A resource object includes the following parameters:
displayName
: String. This should always beResource
.name
: String. This should always beresource
.type
: String. Tells n8n which UI element to use, and what type of input to expect. For example,options
results in n8n adding a dropdown that allows users to choose one option. Refer to Node UI elements for more information.noDataExpression
: Boolean. Prevents using an expression for the parameter. Must always betrue
forresource
.
Operations objects#
The operations object defines the available operations on a resource.
displayName
: String. This should always beOptions
.name
: String. This should always beoption
.type
: String. Tells n8n which UI element to use, and what type of input to expect. For example,dateTime
results in n8n adding a date picker. Refer to Node UI elements for more information.noDataExpression
: Boolean. Prevents using an expression for the parameter. Must always betrue
foroperation
.options
: Array of objects. Each objects describes an operation's behavior, such as its routing, the REST verb it uses, and so on. Anoptions
object includes:name
. String.value
. String.action
: String. This parameter combines the resource and operation. You should always include it, as n8n will use it in future versions. For example, given a resource called"Card"
and an operation"Get all"
, your action is"Get all cards"
.description
: String.routing
: Object containing request details.
Additional fields objects#
These objects define optional parameters. n8n displays them under Additional Fields in the GUI. Users can choose which parameters to set.
The objects must include:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
For more information about UI element types, refer to UI elements.
Declarative-style parameters#
methods and loadOptions#
Object | Optional
methods
contains the loadOptions
object. You can use loadOptions
to query the service to get user-specific settings, then return them and render them in the GUI so the user can include them in subsequent queries. The object must include routing information for how to query the service, and output settings that define how to handle the returned options. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
routing#
Object | Required
routing
is an object used within an options
array in operations and input field objects. It contains the details of an API call.
The code example below comes from the Declarative-style tutorial. It sets up an integration with a NASA API. It shows how to use requestDefaults
to set up the basic API call details, and routing
to add information for each operation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
|
version#
Number or array | Optional
If you have one version of your node, this can be a number. If you want to support more than one version, turn this into an array, containing numbers for each node version.
n8n supports two methods of node versioning, but declarative-style nodes must use the light versioning approach. Refer to Node versioning for more information.
Programmatic-style parameters#
defaultVersion#
Number | Optional
Use defaultVersion
when using the full versioning approach.
n8n support two methods of node versioning. Refer to Node versioning for more information.
methods and loadOptions#
Object | Optional
Contains the loadOptions
method for programmatic-style nodes. You can use this method to query the service to get user-specific settings (such as getting a user's email labels from Gmail), then return them and render them in the GUI so the user can include them in subsequent queries.
For example, n8n's Gmail node uses loadOptions
to get all email labels:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
version#
Number or array | Optional
Use version
when using the light versioning approach.
If you have one version of your node, this can be a number. If you want to support multiple versions, turn this into an array, containing numbers for each node version.
n8n support two methods of node versioning. Programmatic-style nodes can use either. Refer to Node versioning for more information.
Programmatic-style: The execute() method#
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 requests using the routing
key in the operations
object.
The execute()
method creates and returns an instance of INodeExecutionData
.
Paired items
You must include input and output item pairing information in the data you return. For more information, refer to Paired items.