Great that you are here and you want to contribute to n8n
- Contributing to n8n
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].
n8n is split up in different modules which are all in a single mono repository.
The most important directories:
- /docker/image - Dockerfiles to create n8n containers
- /packages - The different n8n modules
- /packages/cli - CLI code to run front- & backend
- /packages/core - Core code which handles workflow execution, active webhooks and workflows. Contact n8n before starting on any changes here
- /packages/design-system - Vue frontend components
- /packages/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
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:
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.
Node.js version 20.15 or newer is required for development purposes.
pnpm version 9.1 or newer is required for development purposes. We recommend installing it with corepack.
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.
We recommend enabling Node.js corepack with corepack enable.
With Node.js v16.17 or newer, you can install the latest version of pnpm: corepack prepare pnpm@latest --activate. If you use an older version install at least version 7.18 of pnpm via: 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 pnpm --activate in a terminal as an administrator.
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.
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:
-
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
upstreamto your forked repository:git remote add upstream https://github.com/n8n-io/n8n.git -
Install all dependencies of all modules and link them together:
pnpm install -
Build all the code:
pnpm build
To start n8n execute:
pnpm start
To start n8n with tunnel:
./packages/cli/bin/n8n start --tunnel
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.
- Start n8n in development mode:
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
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.
- 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.
- Do not use
- 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)
- PRs must include tests:
- Typos:
- Use a spell-checking tool, such as Code Spell Checker, to avoid typos.
- 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.
- 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.
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.
pnpm cypress:install to install cypress before running the tests for the first time and to update cypress.
E2E tests can be started via one of the following commands:
pnpm test:e2e:ui: Start n8n and run e2e tests interactively using built UI code. Does not react to code changes (i.e. runspnpm startandcypress open)pnpm test:e2e:dev: Start n8n in development mode and run e2e tests interactively. Reacts to code changes (i.e. runspnpm devandcypress open)pnpm test:e2e:all: Start n8n and run e2e tests headless (i.e. runspnpm startandcypress run --headless)
To start a release, trigger this workflow with the SemVer release type, and select a branch to cut this release from. This workflow will then:
- Bump versions of packages that have changed or have dependencies that have changed
- Update the Changelog
- Create a new branch called
release/${VERSION}, and - Create a new pull-request to track any further changes that need to be included in this release
Once ready to release, simply merge the pull-request. This triggers another workflow, that will:
- Build and publish the packages that have a new version in this release
- Create a new tag, and GitHub release from squashed release commit
- Merge the squashed release commit back into
master
Learn about building nodes to create custom nodes for n8n. You can create community nodes and make them available using npm.
The repository for the n8n documentation on docs.n8n.io can be found here.
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.
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.