Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides a comprehensive overview for developers wishing to contribute to the n8n project. n8n is a workflow automation platform built with TypeScript in a monorepo structure. It comprises a Node.js backend, a Vue.js frontend, and an extensible node-based workflow engine. Adherence to these guidelines ensures code quality, consistency, and a smooth contribution process.
All participation in the project is governed by the Code of Conduct. By participating, you are expected to uphold this code.
Sources: CONTRIBUTING.md:1-5, 12-16, CLAUDE.md:5-8
Project Architecture
n8n utilizes a monorepo structure managed by pnpm workspaces and orchestrated by Turborepo. This structure isolates packages while facilitating inter-dependencies.
Sources: CLAUDE.md:40, CONTRIBUTING.md:31-34
Monorepo Configuration
The monorepo is defined by pnpm-workspace.yaml, which includes all directories under the packages folder.
# pnpm-workspace.yaml
packages:
- 'packages/**'
Sources: pnpm-workspace.yaml:1-3
Build orchestration is managed by turbo.json, which defines the pipeline for tasks like build, dev, test, lint, and typecheck. It configures caching and task dependencies to optimize build times.
// turbo.json
{
"$schema": "https://turbo.build/schema.json",
"globalDependencies": ["pnpm-lock.yaml"],
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", "vue-dist/**"]
},
"dev": {
"cache": false
},
"test": {
"dependsOn": ["build"],
"outputs": ["coverage/**"]
},
"lint": {},
"typecheck": {
"dependsOn": ["^build"]
}
}
}
Sources: turbo.json:1-22
Key Packages
The repository is organized into several key packages, each with a specific responsibility.
The diagram below illustrates the high-level structure of the n8n monorepo.
Sources: CONTRIBUTING.md:18-30, CLAUDE.md:44-55
| Package | Description | Source File |
|---|---|---|
packages/cli | Contains the Express server, REST API, and CLI commands. | CONTRIBUTING.md:21 |
packages/core | Handles core workflow execution, active webhooks, and workflows. | CONTRIBUTING.md:22-25 |
packages/frontend/editor-ui | The Vue.js frontend for the workflow editor. | CONTRIBUTING.md:27 |
packages/frontend/@n8n/design-system | The Vue component library for UI consistency. | CLAUDE.md:53 |
packages/nodes-base | Contains all base n8n nodes for various integrations. | CONTRIBUTING.md:28 |
packages/workflow | Defines workflow code and interfaces used by both frontend and backend. | CONTRIBUTING.md:29-30 |
packages/@n8n/i18n | Manages internationalization for all UI text. | CLAUDE.md:49 |
Development Setup
To contribute to n8n, you must set up a local development environment.
Sources: CONTRIBUTING.md:36-40
Requirements
Ensure the following tools are installed on your system. Using corepack is the recommended way to manage pnpm.
| Tool | Version | Installation Command | Notes |
|---|---|---|---|
| Node.js | 22.16 or newer | - | Required for development. |
| pnpm | 10.2 or newer | corepack enable then corepack prepare --activate | The required package manager for the monorepo. |
| Build Tools | - | apt-get install build-essential python (Debian) | Varies by OS. Needed for native dependencies. |
Sources: CONTRIBUTING.md:43-77
Initial Setup Workflow
Follow these steps to get your local environment running. This process involves forking the repository, cloning it, installing dependencies, and performing an initial build.
This flowchart shows the sequence of commands for setting up the development environment.
Sources: CONTRIBUTING.md:83-110
Starting n8n
Once the setup is complete, you can start the n8n instance.
- Standard Start:
pnpm start - With Tunnel for Webhooks:
./packages/cli/bin/n8n start --tunnel(for local development and testing only)
Sources: CONTRIBUTING.md:112-120, docker/images/n8n/README.md:68-79
Development Cycle
The typical development cycle involves coding, building, and testing. The project provides scripts to streamline this process.
This flowchart outlines the recommended development workflow.
Sources: CONTRIBUTING.md:122-137
Development Commands
Several pnpm scripts are available to aid development, especially for performance in a large monorepo.
| Command | Description |
|---|---|
pnpm dev | Runs all packages in development mode with hot-reloading. |
pnpm dev:be | Runs backend-only packages. |
pnpm dev:fe | Runs the backend server and frontend dev server. |
pnpm dev:ai | Runs only essential packages for AI/LangChain node development. |
N8N_DEV_RELOAD=true pnpm dev | Enables hot reload for custom nodes and credentials. |
Sources: CONTRIBUTING.md:123-189
Code Quality and Git Hooks
The project uses lefthook to manage git hooks, ensuring code quality before commits. These hooks automatically run lint and typecheck commands.
The lefthook.yml file defines pre-push hooks that run actionlint for GitHub Actions validation and turbo for linting and type-checking affected packages.
# lefthook.yml
pre-push:
parallel: true
commands:
actionlint:
glob: .github/workflows/*.{yml,yaml}
run: actionlint {files}
lint:
run: pnpm turbo lint --filter="...[origin/main]"
typecheck:
run: pnpm turbo typecheck --filter="...[origin/main]"
Sources: lefthook.yml, CLAUDE.md:32-38
Testing
A robust testing suite is crucial. PRs must include tests.
Sources: CONTRIBUTING.md:214-216
Unit Tests
- Run all unit tests with
pnpm test. - To update snapshots, use
pnpm test -- -u. - Code coverage can be generated by setting the
COVERAGE_ENABLEDenvironment variable totrue.
Sources: CONTRIBUTING.md:251-264
End-to-End (E2E) Tests
- n8n uses Playwright for E2E testing. New tests should be written in Playwright, as Cypress is being phased out.
- The Playwright test architecture follows a four-layer approach for UI testing to ensure separation of concerns.
Sources: CONTRIBUTING.md:266-276, CLAUDE.md:110-112, packages/testing/playwright/CONTRIBUTING.md:28-34
This diagram shows the layered architecture for UI tests in Playwright.
- Page Objects: Contain element locators and simple interaction methods.
- Composables: Orchestrate multi-step business workflows across different pages.
- Tests: Describe high-level scenarios using composables.
For detailed guidance on writing Playwright tests, refer to packages/testing/playwright/CONTRIBUTING.md.
Sources: packages/testing/playwright/CONTRIBUTING.md:40-45
Pull Request Guidelines
To ensure a smooth review process, all pull requests (PRs) must adhere to specific guidelines.
General Requirements
- Style Guide: Code must follow n8n's coding standards.
- TypeScript Compliance: Do not use
ts-ignore. - Code Reuse: Avoid duplicating existing components or logic.
- Testing: All PRs must include relevant unit, workflow, or UI tests.
- Small PRs: Each PR should focus on a single feature or fix.
- Naming Convention: Follow the PR title conventions outlined in
.github/pull_request_title_conventions.md.
Sources: CONTRIBUTING.md:200-226
PR Policies
- New Nodes: PRs for new nodes are automatically closed unless explicitly requested by the n8n team.
- Typos: PRs that only fix typos will be rejected.
- Inactivity: PRs with requested changes will be auto-closed after 14 days of inactivity.
Sources: CONTRIBUTING.md:227-238
Contributor License Agreement (CLA)
A Contributor License Agreement must be signed before a PR can be merged. An automated bot will prompt for a signature in the PR comment section.
Sources: CONTRIBUTING.md:304-312
PR Submission and Review Flow
The following diagram illustrates the lifecycle of a pull request.
Sources: CONTRIBUTING.md:198-200, 304-312
Creating Custom Nodes
n8n is extensible, and the community is encouraged to build custom nodes. The @n8n/create-node package provides a scaffolding tool to simplify this process.
To create a new node, run:
npm create @n8n/node@latest
This command initiates an interactive setup process to configure the new node project.
Sources: packages/@n8n/create-node/README.md:5-9
The generated project includes scripts for development, building, linting, and publishing.
| Command | Description |
|---|---|
npm run dev | Starts n8n with the custom node in hot-reload mode. |
npm run build | Compiles the node for production. |
npm run lint | Lints the node's source code. |
npm run release | Publishes the node package to npm. |
Sources: packages/@n8n/create-node/README.md:60-81
For more details, refer to the official documentation on creating nodes.
Sources: CONTRIBUTING.md:293-295
Other Contributions
Documentation
The documentation is hosted in a separate repository. Contributions to improve it are welcome.
- Docs Repository: `https://github.com/n8n-io/n8n-docs%60
Sources: CONTRIBUTING.md:297-299
Workflow Templates
You can submit your own workflows to be included in n8n's official template library.
- Creator Hub: n8n Creator hub
Sources: CONTRIBUTING.md:301-303