Contributing to n8n

Great that you are here and you want to contribute to n8n

Contributing to n8n

Code of conduct

This project and everyone participating in it are governed by the Code of Conduct which can be found in the file CODE_OF_CONDUCT.md. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Directory structure

n8n is split up in different modules which are all in a single mono repository.

The most important directories:

/docker/images - Dockerfiles to create n8n containers
/packages - The different n8n modules
/packages/cli - CLI code to run front- & backend; this also contains the code for n8n's APIs
/packages/core - Core code which handles workflow execution, active webhooks and workflows. Contact n8n before starting on any changes here
/packages/frontend/@n8n/design-system - Vue frontend components
/packages/frontend/editor-ui - Vue frontend workflow editor
/packages/node-dev - CLI to create new n8n-nodes
/packages/nodes-base - Base n8n nodes
/packages/workflow - Workflow code with interfaces which get used by front- & backend

Development setup

If you want to change or extend n8n you have to make sure that all the needed dependencies are installed and the packages get linked correctly. Here's a short guide on how that can be done:

Dev Container

If you already have VS Code and Docker installed, you can click here to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use.

Requirements

Node.js

Node.js version 22.16 or newer is required for development purposes.

pnpm

pnpm version 10.22 or newer is required for development purposes. We recommend installing it with corepack.

pnpm workspaces

n8n is split up into different modules which are all in a single mono repository. To facilitate the module management, pnpm workspaces are used. This automatically sets up file-links between modules which depend on each other.

corepack

We recommend enabling Node.js corepack and pnpm with:

corepack enable
corepack prepare [email protected] --activate

IMPORTANT: If you have installed Node.js via homebrew, you'll need to run

brew install corepack

, since homebrew explicitly removes

npm

and

corepack

from the

node

formula.

IMPORTANT: If you are on windows, you'd need to run

corepack enable

and

corepack prepare --activate

in a terminal as an administrator.

Build tools

The packages which n8n uses depend on a few build tools:

Debian/Ubuntu:

apt-get install -y build-essential python

CentOS:

yum install gcc gcc-c++ make

Windows:

npm add -g windows-build-tools

MacOS:

No additional packages required.

actionlint (for GitHub Actions workflow development)

If you plan to modify GitHub Actions workflow files (

.github/workflows/*.yml

), you'll need actionlint for workflow validation:

macOS (Homebrew):

brew install actionlint

Note: actionlint is only required if you're modifying workflow files. It runs automatically via git hooks when workflow files are changed.

Actual n8n setup

IMPORTANT: All the steps below have to get executed at least once to get the development setup up and running!

Now that everything n8n requires to run is installed, the actual n8n code can be checked out and set up:

For external contributors

Fork the n8n repository.

Clone your forked repository:

git clone https://github.com/<your_github_username>/n8n.git

Go into repository folder:
```
cd n8n
```

Add the original n8n repository as

upstream

to your forked repository:

git remote add upstream https://github.com/n8n-io/n8n.git

For everyone

Go into the cloned repository folder
Install all dependencies of all modules and link them together:
```
pnpm install
```
Build all the code:
```
pnpm build
```

Start

To start n8n execute:

pnpm start

Development cycle

While iterating on n8n modules code, you can run

pnpm dev

. It will then automatically build your code, restart the backend and refresh the frontend (editor-ui) on every change you make. Given the size of the code base and the number of modules, we recommend only watching the modules you're actively working on.

Basic Development Workflow Example (most used within n8n)

If you're working on API and FE, a lot of team members run the following steps:

Start n8n in development mode:

# Terminal 1: CLI code runs the backend
cd packages/cli
pnpm dev

# Terminal 2: Vue frontend workflow editor
cd packages/frontend/editor-ui
pnpm dev

Hack, hack, hack

Check if everything still runs in production mode:

pnpm build
pnpm start

Create tests
Run all tests:
```
pnpm test
```
Commit code and create a pull request

Note: If you're changing code outside of

packages/cli

and

packages/frontend/editor-ui

in this setup, please re-run

pnpm build

Selective Package Development

Running all packages in development mode can be resource-intensive. For better performance, run only the packages relevant to your work:

Available Filtered Commands

Backend-only development:
```
pnpm dev:be
```
Excludes frontend packages like editor-ui and design-system
Frontend-only development:
```
pnpm dev:fe
```
Runs editor-ui & design system development server
AI/LangChain nodes development:
```
pnpm dev:ai
```
Runs only essential packages for AI node development

Custom Selective Development

For even more focused development, you can run packages individually:

Example 1: Working on custom nodes

# Terminal 1: Build and watch nodes package
cd packages/nodes-base
pnpm dev

# Terminal 2: Run the CLI with hot reload
cd packages/cli
N8N_DEV_RELOAD=true pnpm dev

Example 2: Pure frontend development

# Terminal 1: Start the backend server (no watching)
pnpm start

# Terminal 2: Run frontend dev server
cd packages/editor-ui
pnpm dev

Example 3: Working on a specific node package

# Terminal 1: Watch your node package
cd packages/nodes-base  # or your custom node package
pnpm watch

# Terminal 2: Run CLI with hot reload
cd packages/cli
N8N_DEV_RELOAD=true pnpm dev

Running the BE server with a clean database

If you want to flush your existing database, you can delete the

~/.n8n

folder. However, there might be times where you want to test a feature in a clean n8n set-up without losing your existing local setup. In such use cases, you can specify another

N8N_USER_FOLDER

, e.g.:

packages/cli$ N8N_USER_FOLDER=~/.n8n3/ pnpm run dev
packages/cli$ N8N_USER_FOLDER=~/.n8n4/ pnpm run dev

Hot Reload for Nodes (N8N_DEV_RELOAD)

When developing custom nodes or credentials, you can enable hot reload to automatically detect changes without restarting the server by setting

N8N_DEV_RELOAD=true pnpm dev

Performance considerations:

File watching adds overhead to your system, especially on slower machines
The watcher monitors potentially thousands of files, which can impact CPU and memory usage
On resource-constrained systems, consider developing without hot reload and manually restarting when needed

Run local instances in different configurations

We use Testcontainers to easily and quickly spin up a local instance with multiple different configurations for testing.

1. Get a Docker image

You can either build one from your own branch:

pnpm build:docker

or set an environment variable to use a different image:

N8N_DOCKER_IMAGE=n8nio/n8n:latest

2. Run a stack

SQLite:

pnpm --filter n8n-containers stack:sqlite

Postgres:

pnpm --filter n8n-containers stack:postgres

Queue:

pnpm --filter n8n-containers stack:queue

Multi-Main:

pnpm --filter n8n-containers stack:multi-main

3. Customize or scale

Customize with environment variables:

pnpm --filter n8n-containers stack --env N8N_ENABLED_MODULES=insights

Or scale up:

pnpm --filter n8n-containers stack --queue --mains 4 --workers 20

Each instance gets its own port, and the webhook URL matches the main URL. Multi-main stacks use a load balancer by default.

Running testcontainers with docker alternatives

This does not work with Podman out of the box. You need to configure Testcontainers for Podman first.

Alternatively, you can use colima and set DOCKER_HOST and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variables as described here

Refer to packages/testing/containers/README.md for more information.

Work locally with syslog

For manual testing of the event bus with syslog (TCP or UDP), see packages/cli/test/integration/eventbus/README-manual-test-syslog.md. An enterprise license is required to configure syslog in n8n.

Performance Considerations

The full development mode (

pnpm dev

) runs multiple processes in parallel:

TypeScript compilation for each package
File watchers monitoring source files
Nodemon restarting the backend on changes
Vite dev server for the frontend with HMR
Multiple build processes for various packages

Performance impact:

Can consume significant CPU and memory resources
File system watching creates overhead, especially on:
- Networked file systems
- Virtual machines with shared folders
- Systems with slower I/O performance
The more packages you run in dev mode, the more system resources are consumed

Recommendations for resource-constrained environments:

Use selective development commands based on your task
Close unnecessary applications to free up resources
Monitor system performance and adjust your development approach accordingly

Community PR Guidelines

1. Change Request/Comment

Please address the requested changes or provide feedback within 14 days. If there is no response or updates to the pull request during this time, it will be automatically closed. The PR can be reopened once the requested changes are applied.

2. General Requirements

Follow the Style Guide:
- Ensure your code adheres to n8n's coding standards and conventions (e.g., formatting, naming, indentation). Use linting tools where applicable.
TypeScript Compliance:
- Do not use
```
ts-ignore
```
  .
- Ensure code adheres to TypeScript rules.
Avoid Repetitive Code:
- Reuse existing components, parameters, and logic wherever possible instead of redefining or duplicating them.
- For nodes: Use the same parameter across multiple operations rather than defining a new parameter for each operation (if applicable).
Testing Requirements:
- PRs must include tests:
  - Unit tests
  - Workflow tests for nodes (example here)
  - UI tests (if applicable)
Typos:
- Use a spell-checking tool, such as Code Spell Checker, to avoid typos.

3. PR Specific Requirements

Small PRs Only:
- Focus on a single feature or fix per PR.
Naming Convention:
- Follow n8n's PR Title Conventions.
New Nodes:
- PRs that introduce new nodes will be auto-closed unless they are explicitly requested by the n8n team and aligned with an agreed project scope. However, you can still explore building your own nodes, as n8n offers the flexibility to create your own custom nodes.
Typo-Only PRs:
- Typos are not sufficient justification for a PR and will be rejected.

4. Workflow Summary for Non-Compliant PRs

No Tests: If tests are not provided, the PR will be auto-closed after 14 days.
Non-Small PRs: Large or multifaceted PRs will be returned for segmentation.
New Nodes/Typo PRs: Automatically rejected if not aligned with project scope or guidelines.

Test suite

Unit tests

Unit tests can be started via:

pnpm test

If that gets executed in one of the package folders it will only run the tests of this package. If it gets executed in the n8n-root folder it will run all tests of all packages.

If you made a change which requires an update on a

.test.ts.snap

file, pass

-u

to the command to run tests or press

in watch mode.

Code Coverage

We track coverage for all our code on Codecov. But when you are working on tests locally, we recommend running your tests with env variable

COVERAGE_ENABLED

set to

true

. You can then view the code coverage in the

coverage

folder, or you can use this VSCode extension to visualize the coverage directly in VSCode.

E2E tests

n8n uses Playwright for E2E testing.

E2E tests can be started via one of the following commands:

```
pnpm --filter=n8n-playwright test:local
```
- Run tests locally (starts local server on port 5680 and runs UI tests)
```
pnpm --filter=n8n-playwright test:local --ui
```
- Run tests in interactive UI mode (useful for debugging)

pnpm --filter=n8n-playwright test:local --grep="test-name"

- Run specific tests matching pattern

See

packages/testing/playwright/README.md

for more test commands and

packages/testing/playwright/CONTRIBUTING.md

for writing guidelines.

Create custom nodes

Learn about building nodes to create custom nodes for n8n. You can create community nodes and make them available using npm.

Extend documentation

The repository for the n8n documentation on docs.n8n.io can be found here.

Contribute workflow templates

You can submit your workflows to n8n's template library.

n8n is working on a creator program, and developing a marketplace of templates. This is an ongoing project, and details are likely to change.

Refer to n8n Creator hub for information on how to submit templates and become a creator.

Contributor License Agreement

That we do not have any potential problems later it is sadly necessary to sign a Contributor License Agreement. That can be done literally with the push of a button.

We used the most simple one that exists. It is from Indie Open Source which uses plain English and is literally only a few lines long.

Once a pull request is opened, an automated bot will promptly leave a comment requesting the agreement to be signed. The pull request can only be merged once the signature is obtained.

Contributing to n8n

Great that you are here and you want to contribute to n8n

Contributing to n8n

Code of conduct

Directory structure

n8n is split up in different modules which are all in a single mono repository.

The most important directories:

/docker/images - Dockerfiles to create n8n containers
/packages - The different n8n modules
/packages/cli - CLI code to run front- & backend; this also contains the code for n8n's APIs
/packages/core - Core code which handles workflow execution, active webhooks and workflows. Contact n8n before starting on any changes here
/packages/frontend/@n8n/design-system - Vue frontend components
/packages/frontend/editor-ui - Vue frontend workflow editor
/packages/node-dev - CLI to create new n8n-nodes
/packages/nodes-base - Base n8n nodes
/packages/workflow - Workflow code with interfaces which get used by front- & backend

Development setup

If you want to change or extend n8n you have to make sure that all the needed dependencies are installed and the packages get linked correctly. Here's a short guide on how that can be done:

Dev Container

Requirements

Node.js

Node.js version 22.16 or newer is required for development purposes.

pnpm

pnpm version 10.22 or newer is required for development purposes. We recommend installing it with corepack.

pnpm workspaces

corepack

We recommend enabling Node.js corepack and pnpm with:

corepack enable
corepack prepare [email protected] --activate

IMPORTANT: If you have installed Node.js via homebrew, you'll need to run

brew install corepack

, since homebrew explicitly removes

npm

and

corepack

from the

node

formula.

IMPORTANT: If you are on windows, you'd need to run

corepack enable

and

corepack prepare --activate

in a terminal as an administrator.

Build tools

The packages which n8n uses depend on a few build tools:

Debian/Ubuntu:

apt-get install -y build-essential python

CentOS:

yum install gcc gcc-c++ make

Windows:

npm add -g windows-build-tools

MacOS:

No additional packages required.

actionlint (for GitHub Actions workflow development)

If you plan to modify GitHub Actions workflow files (

.github/workflows/*.yml

), you'll need actionlint for workflow validation:

macOS (Homebrew):

brew install actionlint

Note: actionlint is only required if you're modifying workflow files. It runs automatically via git hooks when workflow files are changed.

Actual n8n setup

IMPORTANT: All the steps below have to get executed at least once to get the development setup up and running!

Now that everything n8n requires to run is installed, the actual n8n code can be checked out and set up:

For external contributors

Fork the n8n repository.

Clone your forked repository:

git clone https://github.com/<your_github_username>/n8n.git

Go into repository folder:
```
cd n8n
```

Add the original n8n repository as

upstream

to your forked repository:

git remote add upstream https://github.com/n8n-io/n8n.git

For everyone

Go into the cloned repository folder
Install all dependencies of all modules and link them together:
```
pnpm install
```
Build all the code:
```
pnpm build
```

Start

To start n8n execute:

pnpm start

Development cycle

While iterating on n8n modules code, you can run

pnpm dev

Basic Development Workflow Example (most used within n8n)

If you're working on API and FE, a lot of team members run the following steps:

Start n8n in development mode:

# Terminal 1: CLI code runs the backend
cd packages/cli
pnpm dev

# Terminal 2: Vue frontend workflow editor
cd packages/frontend/editor-ui
pnpm dev

Hack, hack, hack

Check if everything still runs in production mode:

pnpm build
pnpm start

Create tests
Run all tests:
```
pnpm test
```
Commit code and create a pull request

Note: If you're changing code outside of

packages/cli

and

packages/frontend/editor-ui

in this setup, please re-run

pnpm build

Selective Package Development

Running all packages in development mode can be resource-intensive. For better performance, run only the packages relevant to your work:

Available Filtered Commands

Backend-only development:
```
pnpm dev:be
```
Excludes frontend packages like editor-ui and design-system
Frontend-only development:
```
pnpm dev:fe
```
Runs editor-ui & design system development server
AI/LangChain nodes development:
```
pnpm dev:ai
```
Runs only essential packages for AI node development

Custom Selective Development

For even more focused development, you can run packages individually:

Example 1: Working on custom nodes

# Terminal 1: Build and watch nodes package
cd packages/nodes-base
pnpm dev

# Terminal 2: Run the CLI with hot reload
cd packages/cli
N8N_DEV_RELOAD=true pnpm dev

Example 2: Pure frontend development

# Terminal 1: Start the backend server (no watching)
pnpm start

# Terminal 2: Run frontend dev server
cd packages/editor-ui
pnpm dev

Example 3: Working on a specific node package

# Terminal 1: Watch your node package
cd packages/nodes-base  # or your custom node package
pnpm watch

# Terminal 2: Run CLI with hot reload
cd packages/cli
N8N_DEV_RELOAD=true pnpm dev

Running the BE server with a clean database

If you want to flush your existing database, you can delete the

~/.n8n

folder. However, there might be times where you want to test a feature in a clean n8n set-up without losing your existing local setup. In such use cases, you can specify another

N8N_USER_FOLDER

, e.g.:

packages/cli$ N8N_USER_FOLDER=~/.n8n3/ pnpm run dev
packages/cli$ N8N_USER_FOLDER=~/.n8n4/ pnpm run dev

Hot Reload for Nodes (N8N_DEV_RELOAD)

When developing custom nodes or credentials, you can enable hot reload to automatically detect changes without restarting the server by setting

N8N_DEV_RELOAD=true pnpm dev

Performance considerations:

File watching adds overhead to your system, especially on slower machines
The watcher monitors potentially thousands of files, which can impact CPU and memory usage
On resource-constrained systems, consider developing without hot reload and manually restarting when needed

Run local instances in different configurations

We use Testcontainers to easily and quickly spin up a local instance with multiple different configurations for testing.

1. Get a Docker image

You can either build one from your own branch:

pnpm build:docker

or set an environment variable to use a different image:

N8N_DOCKER_IMAGE=n8nio/n8n:latest

2. Run a stack

SQLite:

pnpm --filter n8n-containers stack:sqlite

Postgres:

pnpm --filter n8n-containers stack:postgres

Queue:

pnpm --filter n8n-containers stack:queue

Multi-Main:

pnpm --filter n8n-containers stack:multi-main

3. Customize or scale

Customize with environment variables:

pnpm --filter n8n-containers stack --env N8N_ENABLED_MODULES=insights

Or scale up:

pnpm --filter n8n-containers stack --queue --mains 4 --workers 20

Each instance gets its own port, and the webhook URL matches the main URL. Multi-main stacks use a load balancer by default.

Running testcontainers with docker alternatives

This does not work with Podman out of the box. You need to configure Testcontainers for Podman first.

Alternatively, you can use colima and set DOCKER_HOST and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variables as described here

Refer to packages/testing/containers/README.md for more information.

Work locally with syslog

For manual testing of the event bus with syslog (TCP or UDP), see packages/cli/test/integration/eventbus/README-manual-test-syslog.md. An enterprise license is required to configure syslog in n8n.

Performance Considerations

The full development mode (

pnpm dev

) runs multiple processes in parallel:

TypeScript compilation for each package
File watchers monitoring source files
Nodemon restarting the backend on changes
Vite dev server for the frontend with HMR
Multiple build processes for various packages

Performance impact:

Can consume significant CPU and memory resources
File system watching creates overhead, especially on:
- Networked file systems
- Virtual machines with shared folders
- Systems with slower I/O performance
The more packages you run in dev mode, the more system resources are consumed

Recommendations for resource-constrained environments:

Use selective development commands based on your task
Close unnecessary applications to free up resources
Monitor system performance and adjust your development approach accordingly

Community PR Guidelines

1. Change Request/Comment

2. General Requirements

Follow the Style Guide:
- Ensure your code adheres to n8n's coding standards and conventions (e.g., formatting, naming, indentation). Use linting tools where applicable.
TypeScript Compliance:
- Do not use
```
ts-ignore
```
  .
- Ensure code adheres to TypeScript rules.
Avoid Repetitive Code:
- Reuse existing components, parameters, and logic wherever possible instead of redefining or duplicating them.
- For nodes: Use the same parameter across multiple operations rather than defining a new parameter for each operation (if applicable).
Testing Requirements:
- PRs must include tests:
  - Unit tests
  - Workflow tests for nodes (example here)
  - UI tests (if applicable)
Typos:
- Use a spell-checking tool, such as Code Spell Checker, to avoid typos.

3. PR Specific Requirements

Small PRs Only:
- Focus on a single feature or fix per PR.
Naming Convention:
- Follow n8n's PR Title Conventions.
New Nodes:
- PRs that introduce new nodes will be auto-closed unless they are explicitly requested by the n8n team and aligned with an agreed project scope. However, you can still explore building your own nodes, as n8n offers the flexibility to create your own custom nodes.
Typo-Only PRs:
- Typos are not sufficient justification for a PR and will be rejected.

4. Workflow Summary for Non-Compliant PRs

No Tests: If tests are not provided, the PR will be auto-closed after 14 days.
Non-Small PRs: Large or multifaceted PRs will be returned for segmentation.
New Nodes/Typo PRs: Automatically rejected if not aligned with project scope or guidelines.

Test suite

Unit tests

Unit tests can be started via:

pnpm test

If that gets executed in one of the package folders it will only run the tests of this package. If it gets executed in the n8n-root folder it will run all tests of all packages.

If you made a change which requires an update on a

.test.ts.snap

file, pass

-u

to the command to run tests or press

in watch mode.

Code Coverage

We track coverage for all our code on Codecov. But when you are working on tests locally, we recommend running your tests with env variable

COVERAGE_ENABLED

set to

true

. You can then view the code coverage in the

coverage

folder, or you can use this VSCode extension to visualize the coverage directly in VSCode.

E2E tests

n8n uses Playwright for E2E testing.

E2E tests can be started via one of the following commands:

```
pnpm --filter=n8n-playwright test:local
```
- Run tests locally (starts local server on port 5680 and runs UI tests)
```
pnpm --filter=n8n-playwright test:local --ui
```
- Run tests in interactive UI mode (useful for debugging)

pnpm --filter=n8n-playwright test:local --grep="test-name"

- Run specific tests matching pattern

See

packages/testing/playwright/README.md

for more test commands and

packages/testing/playwright/CONTRIBUTING.md

for writing guidelines.

Create custom nodes

Learn about building nodes to create custom nodes for n8n. You can create community nodes and make them available using npm.

Extend documentation

The repository for the n8n documentation on docs.n8n.io can be found here.

Contribute workflow templates

You can submit your workflows to n8n's template library.

n8n is working on a creator program, and developing a marketplace of templates. This is an ongoing project, and details are likely to change.

Refer to n8n Creator hub for information on how to submit templates and become a creator.

Contributor License Agreement

That we do not have any potential problems later it is sadly necessary to sign a Contributor License Agreement. That can be done literally with the push of a button.

We used the most simple one that exists. It is from Indie Open Source which uses plain English and is literally only a few lines long.

Once a pull request is opened, an automated bot will promptly leave a comment requesting the agreement to be signed. The pull request can only be merged once the signature is obtained.

Contributing to n8n

Related Skills

<h1 align="center">

2. Apply Deepthink Protocol (reason about dependencies

- Identify gaps