n8n/CONTRIBUTING.md

# Contributing to n8n

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

## Contents

- [Contributing to n8n](#contributing-to-n8n)
	- [Contents](#contents)
	- [Code of conduct](#code-of-conduct)
	- [Directory structure](#directory-structure)
	- [Development setup](#development-setup)
		- [Dev Container](#dev-container)
		- [Requirements](#requirements)
			- [Node.js](#nodejs)
			- [pnpm](#pnpm)
				- [pnpm workspaces](#pnpm-workspaces)
			- [corepack](#corepack)
			- [Build tools](#build-tools)
		- [Actual n8n setup](#actual-n8n-setup)
		- [Start](#start)
	- [Development cycle](#development-cycle)
		- [Community PR Guidelines](#community-pr-guidelines)
			- [**1. Change Request/Comment**](#1-change-requestcomment)
			- [**2. General Requirements**](#2-general-requirements)
			- [**3. PR Specific Requirements**](#3-pr-specific-requirements)
			- [**4. Workflow Summary for Non-Compliant PRs**](#4-workflow-summary-for-non-compliant-prs)
		- [Test suite](#test-suite)
			- [Unit tests](#unit-tests)
			- [Code Coverage](#code-coverage)
			- [E2E tests](#e2e-tests)
	- [Releasing](#releasing)
	- [Create custom nodes](#create-custom-nodes)
	- [Extend documentation](#extend-documentation)
	- [Contribute workflow templates](#contribute-workflow-templates)
	- [Contributor License Agreement](#contributor-license-agreement)

## 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](CODE_OF_CONDUCT.md).
By participating, you are expected to uphold this code. Please report
unacceptable behavior to jan@n8n.io.

## Directory structure

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

The most important directories:

- [/docker/images](/docker/images) - Dockerfiles to create n8n containers
- [/packages](/packages) - The different n8n modules
- [/packages/cli](/packages/cli) - CLI code to run front- & backend; this also contains the code for n8n's APIs
- [/packages/core](/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](/packages/frontend/@n8n/design-system) - Vue frontend components
- [/packages/frontend/editor-ui](/packages/frontend/editor-ui) - Vue frontend workflow editor
- [/packages/node-dev](/packages/node-dev) - CLI to create new n8n-nodes
- [/packages/nodes-base](/packages/nodes-base) - Base n8n nodes
- [/packages/workflow](/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](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/n8n-io/n8n) 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](https://nodejs.org/en/) version 24 or newer is required for development purposes.

#### pnpm

[pnpm](https://pnpm.io/) version 10.22 or newer is required for development purposes. We recommend installing it with [corepack](#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](https://pnpm.io/workspaces) are used.
This automatically sets up file-links between modules which depend on each other.

#### corepack

We recommend enabling [Node.js corepack](https://nodejs.org/docs/latest-v16.x/api/corepack.html)  and pnpm with:

```bash
corepack enable
corepack prepare pnpm@10.22.0 --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](https://github.com/Homebrew/homebrew-core/blob/master/Formula/node.rb#L66).

**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:

```bash
apt-get install -y build-essential python
```

CentOS:

```bash
yum install gcc gcc-c++ make
```

Windows:

```bash
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](https://github.com/rhysd/actionlint) for workflow validation:

**macOS (Homebrew):**
```bash
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.

#### tbls (for database schema docs)

The database schema docs under [`docs/generated/`](docs/generated) are generated from the migrations with [tbls](https://github.com/k1LoW/tbls). If you plan to modify DB migrations, you'll need **either** tbls installed **or** Docker available.

**macOS (Homebrew):**
```bash
brew install tbls
```

For other platforms, see the [tbls install guide](https://github.com/k1LoW/tbls#install).

> **Note:** tbls is only required if you're modifying DB migrations. It runs automatically via git hooks when migration 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

1. [Fork](https://guides.github.com/activities/forking/#fork) the n8n repository.

2. Clone your forked repository:

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

3. Go into repository folder:

   ```
   cd n8n
   ```

4. Add the original n8n repository as `upstream` to your forked repository:

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

#### For everyone

1. Go into the cloned repository folder

2. Install all dependencies of all modules and link them together:

   ```
   pnpm install
   ```

3. Build all the code:
   ```
   pnpm build
   ```

### Start

To start n8n execute:

```bash
pnpm start
```

### Environment variables (optional)

Most environment variables have default values, but if you needed to modify any a template for local environment variables is provided at `.env.local.example`. Copy it and fill in any values you need.

```bash
cp .env.local.example .env.local
```

Then prefix any dev command with `dotenvx` to load it, for example:

```bash
cd packages/cli && pnpm exec dotenvx run -f ../../.env.local -- pnpm dev

pnpm exec dotenvx run -f .env.local -- pnpm dev:be
```

> **Note:** dotenvx supports variable expansion (e.g. `$HOME`) but not shell
> tilde expansion. Use `$HOME` instead of `~` for paths
> (e.g. `N8N_USER_FOLDER=$HOME/.n8n-dev`).

## 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:

1. Start n8n in development mode:
```bash
# Terminal 1: CLI code runs the backend
cd packages/cli
pnpm dev
```
```bash
# Terminal 2: Vue frontend workflow editor
cd packages/frontend/editor-ui
pnpm dev
```
2. Hack, hack, hack
3. Check if everything still runs in production mode:
   ```
   pnpm build
   pnpm start
   ```
4. Create tests
5. Run all [tests](#test-suite):
   ```
   pnpm test
   ```
6. Commit code and [create a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)

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:**
  ```bash
  pnpm dev:be
  ```
  Excludes frontend packages like editor-ui and design-system

- **Frontend-only development:**
  ```bash
  pnpm dev:fe
  ```
  Runs editor-ui & design system development server

- **AI/LangChain nodes development:**
  ```bash
  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**
```bash
# 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**
```bash
# 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**
```bash
# 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.:

```bash
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

```bash
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**](https://testcontainers.com/) 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:

```bash
pnpm build:docker
```

or set an environment variable to use a different image:

```bash
N8N_DOCKER_IMAGE=n8nio/n8n:latest
```

**2. Run a stack**

- **SQLite:**

  ```bash
  pnpm --filter n8n-containers stack:sqlite
  ```

- **Postgres:**

  ```bash
  pnpm --filter n8n-containers stack:postgres
  ```

- **Queue:**

  ```bash
  pnpm --filter n8n-containers stack:queue
  ```

- **Multi-Main:**

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

**3. Customize or scale**

Customize with environment variables:

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

Or scale up:

```bash
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](https://podman-desktop.io/tutorial/testcontainers-with-podman) first.
>- Alternatively, you can use colima and set DOCKER_HOST and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variables as described [here](https://node.testcontainers.org/supported-container-runtimes/#colima)

Refer to [packages/testing/containers/README.md](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](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:

1. **TypeScript compilation** for each package
2. **File watchers** monitoring source files
3. **Nodemon** restarting the backend on changes
4. **Vite dev server** for the frontend with HMR
5. **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:**
1. Use selective development commands based on your task
2. Close unnecessary applications to free up resources
3. Monitor system performance and adjust your development approach accordingly

---

### Community PR Guidelines

We read and review every pull request by hand. These guidelines keep that sustainable, and they help you avoid building something we cannot accept. The fastest route to a merge is to agree on the change with us before you write code.

Our golden rule: a contribution should be worth more to the project than the time it takes us to review it.

#### **1. Start With an Issue or Forum Topic**

- **Ask before you start:**
  - If you want to work on an existing issue, comment to ask first and wait for a team member to respond before you pick it up. This avoids two people, including us, building the same fix at the same time.
- **Bug fixes:**
  - An issue must already exist that describes the problem and gives clear steps to reproduce it. If there is no issue, [open one](https://github.com/n8n-io/n8n/issues/new/choose) first.
  - Bug-fix PRs with no linked issue will be returned so we can confirm and track the problem.
- **Features and enhancements:**
  - Open a topic on the [n8n community forum](https://community.n8n.io/) first so we can discuss it before you build. This protects your time: we will tell you early whether we will accept the idea, and we will guide you on how we would want it handled.
  - Feature PRs that arrive with no prior discussion will be closed with a pointer to the forum.
- **Refactoring or opinion-based changes:**
  - Open an issue or forum topic first with a detailed rationale: what you want to change, why, and the concrete benefit. We do not merge "I prefer it this way" changes without that reasoning.
- **Core changes:**
  - Contact n8n before starting any change under [/packages/core](/packages/core), as noted in the directory structure.
- **Identity, access, and credentials:**
  - The n8n team handles changes to identity and access management and to the credentials system. These control how users sign in, what they reach, and how credentials get stored and used. A mistake here risks exposing sensitive data or locking users out, so we keep these in-house. If you spot a bug or have an idea, open an issue or forum topic to flag it and we will take it from there.
- **High-impact nodes:**
  - The n8n team handles changes to the most widely used nodes, including HTTP Request, Code, Webhook Trigger, Form Trigger, and Schedule. A small change to one of these can break workflows for a large number of users, so we keep these in-house. If you spot a bug or have an idea for one of them, open an issue or forum topic to flag it and we will take it from there.

#### **2. 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.

#### **3. General Requirements**

- **Describe Your Change:**
  - Every PR needs a clear description of what you changed, why, and why you took this approach over the alternatives. Link the issue or forum topic. Write the description in your own words. A PR with no real description will be closed.
  - Where possible try to include a short video or screenshots. This is useful if you are working on a feature or updating a node.
- **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` or `ts-expect-error` to silence the compiler.
  - Ensure code adheres to TypeScript rules.
- **Avoid Repetitive Code:**
  - Reuse existing components, parameters, and logic wherever possible instead of redefining or duplicating them.
  - Before writing a constant or helper, check whether one already exists. For nodes, throw `NodeOperationError`/`NodeApiError` (from `n8n-workflow`) rather than raw errors, and use `jsonParse` (from `n8n-workflow`) instead of bare `JSON.parse`. More generally, `@n8n/constants` and `@n8n/utils` hold many reusable helpers — e.g. `Time` from `@n8n/constants` for time-unit math (`5 * Time.minutes.toMilliseconds` instead of `5 * 60 * 1000`).
  - 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
    - Integration tests (if applicable)
    - Workflow tests for nodes (example [here](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Switch/V3/test))
    - UI tests (if applicable)
    - Detailed steps under the "How to test" section of the PR template to cover how to manually test the feature or bug fix.
  - For a **bug fix**, include at least one regression test that **fails against the latest `master`** without your change and passes with it. Tell us in the description how to see it fail, so we can verify the fix actually fixes something.
- **Typos:**
  - Use a spell-checking tool, such as [**Code Spell Checker**](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker), to avoid typos.
- **Verify that your PR contains only your intended changes:**
  - Before opening or requesting review, check the *Files Changed* tab and confirm that all modifications are related to your fix/feature. If you see unrelated file changes, commits from other authors, or a large number of unexpected commits, rebase or recreate your branch against the current `master` branch and clean up the history before submitting.

#### **4. Using AI Tools**

We use AI tools ourselves and we welcome AI-assisted contributions. The problem is not the tool. The problem is code the author cannot stand behind.

- **Understand and own your code:**
  - You must understand every line you submit and be able to explain what it does and how it fits the rest of the system, without the AI. If you cannot, do not open the PR yet.
- **Write the description in your own words:**
  - Write your PR description, issue, and forum posts in your own words. Do not paste raw model output.
- **Same gates apply:**
  - AI-assisted features and refactors still need an accepted issue or forum topic first, the same as any other change.
- **Disclosure:**
  - We encourage you to note in the PR if AI tools did a meaningful part of the work, and which tools. It helps us calibrate review and it is not held against you.

#### **5. PR Specific Requirements**

- **Small PRs Only:**
  - Focus on a single feature or fix per PR.
- **Naming Convention:**
  - Follow [n8n's PR Title Conventions](https://github.com/n8n-io/n8n/blob/master/.github/pull_request_title_conventions.md#L36).
- **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](https://docs.n8n.io/integrations/creating-nodes/overview/), as n8n offers the flexibility to create your own custom nodes.
- **Existing Nodes:**
  - If you are making changes to existing nodes that changes functionality, output data or anything that could cause existing workflows to change refer to our [node version guidelines](https://docs.n8n.io/connect/create-nodes/build-your-node/reference/versioning) to minimise impact.
- **Typo-Only PRs:**
  - Typos are not sufficient justification for a PR and will be rejected. Fold typo fixes into a larger, related change.

#### **6. Workflow Summary for Non-Compliant PRs**

- **No Linked Issue or Discussion:** Bug-fix PRs with no issue, and feature PRs with no forum topic, will be returned or closed per section 1.
- **No Tests:** If tests are not provided, the PR will be auto-closed after **14 days**.
- **Keep PRs small and focused.** Each PR should add no more than 1000 lines and cover one logical change. Larger or multifaceted PRs will be returned for segmentation.
- **New Nodes/Typo PRs:** Automatically rejected if not aligned with project scope or guidelines.
- **Low-Value or Automated PRs:** We close these, and may block accounts that repeat them. This covers:
  - Whitespace, formatting, or reordering changes with no functional reason.
  - Mass find-and-replace or renames submitted with no rationale.
  - Dependency bumps with no explanation of why the bump is needed.
  - README badges, comment tweaks, or restating the obvious.
  - PRs whose main purpose is to earn a contribution credit, a mention, or event points. Hacktoberfest and similar events do not change the quality bar.
  - Bulk or scripted submissions across many files or repositories.

---

### 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 `u` in watch mode.

#### Code Coverage
We track coverage for all our code on [Codecov](https://app.codecov.io/gh/n8n-io/n8n).
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](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) to visualize the coverage directly in VSCode.

#### E2E tests

n8n uses [Playwright](https://playwright.dev) 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](https://docs.n8n.io/integrations/creating-nodes/overview/) to create custom nodes for n8n. You can create community nodes and make them available using [npm](https://www.npmjs.com/).

## Extend documentation

The repository for the n8n documentation on [docs.n8n.io](https://docs.n8n.io) can be found [here](https://github.com/n8n-io/n8n-docs).

## 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](https://www.notion.so/n8n/n8n-Creator-hub-7bd2cbe0fce0449198ecb23ff4a2f76f) 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](CONTRIBUTOR_LICENSE_AGREEMENT.md). 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](https://indieopensource.com/forms/cla) 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.