Skip to content

Node file structure#

Following best practices and standards in your node structure makes your node easier to maintain. It's helpful if other people need to work with the code.

The file and directory structure of your node is affected by:

  • Your node's complexity.
  • Whether you use node versioning.
  • How many nodes you include in the npm package.

Required files and directories#

Your node must include:

  • A package.json file at the root of the project. This is required for any npm module.
  • A nodes directory, containing the code for your node:
    • This directory must contain the base file, in the format <node-name>.node.ts. For example, MyNode.node.ts.
    • n8n recommends including a codex file, containing metadata for your node. The codex filename must match the node base filename. For example, given a node base file named MyNode.node.ts, the codex name is MyNode.node.json.
    • The nodes directory can contain other files and subdirectories, including directories for versions, and node code split across more than one file to create a modular structure.
  • A credentials directory, containing your credentials code. This code lives in a single credentials file. The filename format is <node-name>.credentials.ts. For example, MyNode.credentials.ts.

Modular structure#

You can choose whether to place all your node's functionality in one file, or split it out into a base file and other modules, which the base file then imports. Unless your node is very simple, it's a best practice to split it out.

A basic pattern is to separate out operations. Refer to the HttpBin starter node for an example of this.

For more complex nodes, n8n recommends the following structure:

  • actions: directory with description and implementation of each possible resource and operation.
    • In the actions folder, n8n recommends using resources and operations as the names of the sub-folders.
    • For the implementation and description you can use separate files. Use execute.ts and description.ts as filenames. This makes browsing through the code a lot easier. You can simplify this for nodes that have a less complicated structure.
  • methods: an optional directory dynamic parameters' functions.
  • transport: a directory containing the communication implementation.


If your node has more than one version, and you're using full versioning, this makes the file structure more complex. You need a directory for each version, along with a base file that sets the default version. Refer to Node versioning for more information on working with versions, including types of versioning.

Decide how many nodes to include in a package#

There are two possible setups when building a node:

  • One node in one npm package.
  • More than one node in a single npm package.

n8n supports both approaches. If you include more than one node, each node should have its own directory in the nodes directory.

A best-practice example for programmatic nodes: The Mattermost node#

n8n's built-in Mattermost node implements a modular structure and versioning, following recommended patterns.