2019-08-14 09:30:54 +03:00
# Contributing to n8n
Great that you are here and you want to contribute to n8n
2019-08-22 00:18:09 +03:00
## Contents
2022-11-09 19:32:05 +03:00
- [Contributing to n8n ](#contributing-to-n8n )
2023-11-02 15:17:23 +03:00
- [Contents ](#contents )
- [Code of conduct ](#code-of-conduct )
- [Directory structure ](#directory-structure )
- [Development setup ](#development-setup )
2024-06-06 15:31:33 +03:00
- [Dev Container ](#dev-container )
2023-11-02 15:17:23 +03:00
- [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 )
- [Test suite ](#test-suite )
2023-11-24 14:21:42 +03:00
- [Unit tests ](#unit-tests )
- [E2E tests ](#e2e-tests )
2023-11-02 15:17:23 +03:00
- [Releasing ](#releasing )
- [Create custom nodes ](#create-custom-nodes )
- [Extend documentation ](#extend-documentation )
2023-11-22 14:40:20 +03:00
- [Contribute workflow templates ](#contribute-workflow-templates )
2023-11-02 15:17:23 +03:00
- [Contributor License Agreement ](#contributor-license-agreement )
2019-08-22 00:18:09 +03:00
2021-09-15 08:52:23 +03:00
## Code of conduct
2019-08-14 09:30:54 +03:00
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.
2021-09-15 08:52:23 +03:00
## Directory structure
2019-08-14 09:30:54 +03:00
n8n is split up in different modules which are all in a single mono repository.
The most important directories:
2022-08-19 16:34:02 +03:00
- [/docker/image ](/docker/images ) - Dockerfiles to create n8n containers
- [/docker/compose ](/docker/compose ) - Examples Docker Setups
- [/packages ](/packages ) - The different n8n modules
- [/packages/cli ](/packages/cli ) - CLI code to run front- & backend
- [/packages/core ](/packages/core ) - Core code which handles workflow
execution, active webhooks and
workflows. **Contact n8n before
starting on any changes here**
- [/packages/design-system ](/packages/design-system ) - Vue frontend components
- [/packages/editor-ui ](/packages/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
2019-08-14 09:30:54 +03:00
2021-09-15 08:52:23 +03:00
## Development setup
2019-08-14 09:30:54 +03:00
2023-06-26 12:05:05 +03:00
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:
2019-08-14 09:30:54 +03:00
2024-06-06 15:31:33 +03:00
### 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.
2019-08-14 09:30:54 +03:00
### Requirements
2021-10-15 01:21:04 +03:00
#### Node.js
2024-05-24 13:32:50 +03:00
[Node.js ](https://nodejs.org/en/ ) version 18.10 or newer is required for development purposes.
2022-11-09 19:32:05 +03:00
2023-01-19 12:41:44 +03:00
#### pnpm
2024-06-04 12:44:44 +03:00
[pnpm ](https://pnpm.io/ ) version 9.1 or newer is required for development purposes. We recommend installing it with [corepack ](#corepack ).
2023-01-19 12:41:44 +03:00
##### pnpm workspaces
2023-06-26 12:05:05 +03:00
n8n is split up into different modules which are all in a single mono repository.
2023-01-19 12:41:44 +03:00
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
2023-01-27 12:18:15 +03:00
We recommend enabling [Node.js corepack ](https://nodejs.org/docs/latest-v16.x/api/corepack.html ) with `corepack enable` .
2023-01-19 12:41:44 +03:00
2023-01-27 12:18:15 +03:00
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 pnpm@7.18.0 --activate` .
2022-11-09 19:32:05 +03:00
**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 pnpm --activate` in a terminal as an administrator.
2021-10-15 01:21:04 +03:00
2021-09-15 08:52:23 +03:00
#### Build tools
2019-08-14 09:30:54 +03:00
2019-08-14 14:45:18 +03:00
The packages which n8n uses depend on a few build tools:
2019-08-14 09:30:54 +03:00
2020-09-03 13:45:54 +03:00
Debian/Ubuntu:
2022-08-19 16:34:02 +03:00
2019-08-14 09:30:54 +03:00
```
apt-get install -y build-essential python
```
2020-09-03 13:45:54 +03:00
CentOS:
2022-08-19 16:34:02 +03:00
2020-09-03 13:45:54 +03:00
```
yum install gcc gcc-c++ make
```
2019-08-14 09:30:54 +03:00
Windows:
2022-08-19 16:34:02 +03:00
2019-08-14 09:30:54 +03:00
```
2022-11-09 19:32:05 +03:00
npm add -g windows-build-tools
2019-08-14 09:30:54 +03:00
```
2023-01-19 12:41:44 +03:00
MacOS:
2019-08-14 09:30:54 +03:00
2023-01-19 12:41:44 +03:00
No additional packages required.
2019-08-14 09:30:54 +03:00
### Actual n8n setup
2022-01-15 22:29:27 +03:00
> **IMPORTANT**: All the steps below have to get executed at least once to get the development setup up and running!
2019-10-25 16:28:39 +03:00
2023-06-26 12:05:05 +03:00
Now that everything n8n requires to run is installed, the actual n8n code can be
2019-08-14 09:30:54 +03:00
checked out and set up:
2023-06-26 12:05:05 +03:00
1. [Fork ](https://guides.github.com/activities/forking/#fork ) the n8n repository.
2021-09-15 08:52:23 +03:00
2023-06-26 12:05:05 +03:00
2. Clone your forked repository:
2022-08-19 16:34:02 +03:00
```
git clone https://github.com/< your_github_username > /n8n.git
```
2021-09-15 08:52:23 +03:00
2023-06-26 12:05:05 +03:00
3. Go into repository folder:
2022-08-19 16:34:02 +03:00
```
2022-09-02 17:13:17 +03:00
cd n8n
2022-08-19 16:34:02 +03:00
```
2019-08-14 09:30:54 +03:00
2023-06-26 12:05:05 +03:00
4. Add the original n8n repository as `upstream` to your forked repository:
2022-08-19 16:34:02 +03:00
```
2022-09-02 17:13:17 +03:00
git remote add upstream https://github.com/n8n-io/n8n.git
2022-08-19 16:34:02 +03:00
```
2019-08-14 09:30:54 +03:00
2022-08-06 23:55:51 +03:00
5. Install all dependencies of all modules and link them together:
2022-08-19 16:34:02 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm install
2022-08-19 16:34:02 +03:00
```
2019-08-14 09:30:54 +03:00
2022-08-06 23:55:51 +03:00
6. Build all the code:
2022-08-19 16:34:02 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm build
2022-08-19 16:34:02 +03:00
```
2019-08-14 09:30:54 +03:00
### Start
To start n8n execute:
```
2022-11-09 19:32:05 +03:00
pnpm start
2019-08-14 09:30:54 +03:00
```
2019-08-14 10:14:24 +03:00
2020-09-01 15:41:29 +03:00
To start n8n with tunnel:
2022-08-19 16:34:02 +03:00
2020-09-01 15:41:29 +03:00
```
./packages/cli/bin/n8n start --tunnel
```
2019-08-14 10:14:24 +03:00
2021-09-15 08:52:23 +03:00
## Development cycle
2019-08-14 10:14:24 +03:00
2022-11-09 19:32:05 +03:00
While iterating on n8n modules code, you can run `pnpm dev` . It will then
2019-08-14 14:45:18 +03:00
automatically build your code, restart the backend and refresh the frontend
(editor-ui) on every change you make.
2019-08-14 10:14:24 +03:00
2019-08-14 14:45:18 +03:00
1. Start n8n in development mode:
2022-08-19 16:34:02 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm dev
2022-08-19 16:34:02 +03:00
```
2021-04-07 15:33:16 +03:00
1. Hack, hack, hack
2023-06-26 12:05:05 +03:00
1. Check if everything still runs in production mode:
2022-08-19 16:34:02 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm build
pnpm start
2022-08-19 16:34:02 +03:00
```
2019-08-14 14:45:18 +03:00
1. Create tests
2023-06-26 12:05:05 +03:00
1. Run all [tests ](#test-suite ):
2022-08-19 16:34:02 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm test
2022-08-19 16:34:02 +03:00
```
2021-09-15 08:52:23 +03:00
1. 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 )
2019-08-14 10:14:24 +03:00
### Test suite
2023-11-24 14:21:42 +03:00
#### Unit tests
Unit tests can be started via:
2022-08-19 16:34:02 +03:00
2019-08-14 14:45:18 +03:00
```
2022-11-09 19:32:05 +03:00
pnpm test
2019-08-14 14:45:18 +03:00
```
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.
2019-08-22 00:15:22 +03:00
2023-11-24 14:21:42 +03:00
#### E2E tests
2024-01-27 21:01:17 +03:00
⚠️ You have to run `pnpm cypress:install` to install cypress before running the tests for the first time and to update cypress.
2023-11-24 14:21:42 +03:00
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. runs `pnpm start` and `cypress open` )
- `pnpm test:e2e:dev` : Start n8n in development mode and run e2e tests interactively. Reacts to code changes (i.e. runs `pnpm dev` and `cypress open` )
- `pnpm test:e2e:all` : Start n8n and run e2e tests headless (i.e. runs `pnpm start` and `cypress run --headless` )
⚠️ Remember to stop your dev server before. Otherwise port binding will fail.
2023-02-21 16:04:35 +03:00
## Releasing
2023-06-26 12:05:05 +03:00
To start a release, trigger [this workflow ](https://github.com/n8n-io/n8n/actions/workflows/release-create-pr.yml ) with the SemVer release type, and select a branch to cut this release from. This workflow will then:
2023-02-21 16:04:35 +03:00
1. Bump versions of packages that have changed or have dependencies that have changed
2. Update the Changelog
3. Create a new branch called `release/${VERSION}` , and
4. 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.
2023-06-26 12:05:05 +03:00
This triggers [another workflow ](https://github.com/n8n-io/n8n/actions/workflows/release-publish.yml ), that will:
2023-02-21 16:04:35 +03:00
1. Build and publish the packages that have a new version in this release
2. Create a new tag, and GitHub release from squashed release commit
3. Merge the squashed release commit back into `master`
2021-09-15 08:52:23 +03:00
## Create custom nodes
2019-08-22 00:15:22 +03:00
2023-01-10 18:18:01 +03:00
Learn about [building nodes ](https://docs.n8n.io/integrations/creating-nodes/ ) to create custom nodes for n8n. You can create community nodes and make them available using [npm ](https://www.npmjs.com/ ).
2020-04-28 12:50:20 +03:00
2021-09-15 08:52:23 +03:00
## Extend documentation
2019-10-02 11:00:28 +03:00
2021-04-07 15:33:16 +03:00
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 ).
2019-10-25 23:21:18 +03:00
2023-11-22 14:40:20 +03:00
## 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.
2019-10-25 23:21:18 +03:00
## 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.
2020-06-18 11:08:31 +03:00
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.
2019-10-25 23:21:18 +03:00
2023-06-26 12:05:05 +03:00
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.