Contributing to n8n
Relevant source files
The following files were used as context for generating this wiki page:This guide provides a comprehensive overview for developers looking to contribute to the n8n project. It covers setting up the development environment, understanding the project structure, the development cycle, testing procedures, and the guidelines for submitting pull requests. n8n is a workflow automation platform built with a Node.js backend and a Vue.js frontend, organized as a monorepo.
Contributions can range from core code changes and bug fixes to creating custom nodes, extending documentation, or submitting workflow templates. All contributions are governed by a Code of Conduct and require a Contributor License Agreement.
Sources: CONTRIBUTING.md, README.md, AGENTS.md
Core Principles and Agreements
All participation in the n8n project is subject to the following agreements to ensure a respectful and legally sound collaborative environment.
Code of Conduct
The project is governed by a Code of Conduct that all participants are expected to uphold. The goal is to maintain a positive and inclusive community. Unacceptable behavior should be reported to jan@n8n.io.
Sources: CONTRIBUTING.md:12-15, CODE_OF_CONDUCT.md
Contributor License Agreement (CLA)
To avoid potential legal issues, contributors must sign a Contributor License Agreement (CLA). This is a straightforward process handled by an automated bot. When a pull request is opened, the bot will comment with a link to sign the agreement. The CLA is based on the simple, plain-English version from Indie Open Source. A pull request cannot be merged until the CLA is signed.
Sources: CONTRIBUTING.md:278-285, CONTRIBUTOR_LICENSE_AGREEMENT.md
Development Environment Setup
Setting up a local development environment is the first step to contributing. n8n provides multiple ways to get started, including a standard local setup and a containerized environment.
Prerequisites
Before setting up n8n, you must have the following tools installed:
| Tool | Version | Installation Notes |
|---|---|---|
| Node.js | 22.16 or newer | Required for the development environment. |
| pnpm | 10.2 or newer | The required package manager for the monorepo. |
| corepack | - | Recommended for managing pnpm version. Enable with corepack enable. |
| Build Tools | - | Varies by OS (e.g., build-essential on Debian/Ubuntu). |
Sources: CONTRIBUTING.md:46-77
Setup Steps
The following diagram and steps outline the process for setting up the n8n repository for local development.
This diagram shows the workflow for setting up the n8n development environment, from forking the repository to running the application.
Sources: CONTRIBUTING.md:83-111, README.md:21-22
- Fork the
n8n-io/n8nrepository on GitHub. - Clone your forked repository to your local machine: `git clone https://github.com/%3Cyour_github_username%3E/n8n.git%60
- Navigate into the repository directory:
cd n8n - Add the original repository as an upstream remote: `git remote add upstream https://github.com/n8n-io/n8n.git%60
- Install all dependencies and link the monorepo packages:
pnpm install - Build all the code for the first time:
pnpm build - Start the development server:
pnpm startorpnpm devfor hot-reloading.
Dev Container
For a quicker setup, you can use the provided Dev Container with VS Code and Docker. Clicking the link in CONTRIBUTING.md will automatically clone the repository into a container volume and configure the development environment.
Sources: CONTRIBUTING.md:39-42
Project Structure
n8n is a monorepo managed with pnpm workspaces. This structure facilitates module management by linking packages that depend on each other.
The diagram below illustrates the high-level architecture and some key packages.
This diagram shows the relationships between some of the most important packages in the n8n monorepo.
Sources: CONTRIBUTING.md:18-31, AGENTS.md:36-50
Key Packages
| Directory | Description |
|---|---|
/packages/cli | Contains the Express server, REST API, and CLI commands. |
/packages/core | The core workflow execution engine. Changes here require coordination with the n8n team. |
/packages/frontend/editor-ui | The Vue.js frontend application for the workflow editor. |
/packages/@n8n/design-system | The Vue component library for UI consistency. |
/packages/nodes-base | Contains all the built-in n8n nodes. |
/packages/workflow | Defines core workflow interfaces and types used by both frontend and backend. |
/packages/@n8n/create-node | Scaffolding tool to create new custom community nodes. |
/packages/testing/playwright | Contains the End-to-End (E2E) tests. |
Sources: CONTRIBUTING.md:20-31, AGENTS.md:39-49
Development Cycle
The typical development workflow involves coding, building, and testing. n8n provides scripts to streamline this process.
Basic Development Workflow
The following diagram illustrates the iterative development cycle.
This flowchart shows the standard development loop, from starting the dev server to creating a pull request.
Sources: CONTRIBUTING.md:118-132
Development Commands
n8n offers several commands to optimize the development experience, especially for a large monorepo.
| Command | Description |
|---|---|
pnpm dev | Runs all packages in development mode with hot-reloading. Resource-intensive. |
pnpm dev:be | Runs backend-only packages in development mode. |
pnpm dev:fe | Runs the backend server and the frontend development 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 without a full server restart. |
pnpm lint | Lints the code in the current package. |
pnpm typecheck | Runs TypeScript type checks. |
Sources: CONTRIBUTING.md:134-184, AGENTS.md:27-34
Testing
A comprehensive test suite is crucial for maintaining code quality. Contributions must include relevant tests.
Test Suite Overview
The diagram below shows the different types of tests in the n8n project and how to run them.
This diagram outlines the testing structure, including the frameworks used and the commands to execute different test suites.
Sources: CONTRIBUTING.md:231-260, packages/testing/playwright/CONTRIBUTING.md:4-16, AGENTS.md:88-95
- Unit Tests: Run with
pnpm test. This command can be executed from the root to run all tests or from a specific package directory to run only that package's tests. Jest is used as the test runner. - E2E Tests: n8n uses Playwright for end-to-end testing. Tests are located in
packages/testing/playwright.- Run all local E2E tests:
pnpm --filter=n8n-playwright test:local - Run in interactive UI mode for debugging:
pnpm --filter=n8n-playwright test:local --ui
- Run all local E2E tests:
- Code Coverage: Can be generated locally by setting the
COVERAGE_ENABLED=trueenvironment variable when running tests.
Sources: CONTRIBUTING.md:231-260, packages/testing/playwright/CONTRIBUTING.md, AGENTS.md:88-95
Pull Request Guidelines
To ensure a smooth review process, all pull requests (PRs) must adhere to specific guidelines. Non-compliant PRs may be automatically closed.
PR Requirements
- Small, Focused PRs: Each PR should address a single feature or fix.
- Testing: All PRs must include tests (unit, workflow, or UI). PRs without tests will be auto-closed after 14 days.
- Style Guide Adherence: Code must follow n8n's coding standards.
- TypeScript Compliance: The use of
ts-ignoreis forbidden. - No Repetitive Code: Reuse existing components and logic where possible.
- PR Title Convention: Follow the naming conventions outlined in
.github/pull_request_title_conventions.md.
Sources: CONTRIBUTING.md:191-229
Restrictions
- New Nodes: PRs introducing new nodes will be auto-closed unless explicitly requested by the n8n team. Contributors are encouraged to build and distribute their own custom nodes.
- Typo-Only PRs: PRs that only fix typos will be rejected.
The following flowchart summarizes the PR submission and review workflow.
This diagram shows the decision process for handling community pull requests based on the contribution guidelines.
Sources: CONTRIBUTING.md:191-229
Ways to Contribute
There are several ways to contribute to the n8n ecosystem beyond core code changes.
Create Custom Nodes
While new nodes are not typically accepted into the core repository, n8n provides a powerful toolchain for creating and publishing community nodes.
The @n8n/create-node package scaffolds a new node project with best practices built-in.
Node Creation and Development Lifecycle:
This diagram shows the lifecycle of creating a custom n8n node, from scaffolding to publishing.
The generated project includes scripts for development, building, linting, and releasing your node. The underlying CLI, @n8n/node-cli, handles tasks like running a local n8n instance with hot-reloading for your node.
Sources: packages/@n8n/create-node/README.md, packages/@n8n/node-cli/README.md, CONTRIBUTING.md:262-265
Other Contributions
- Extend Documentation: The n8n documentation is in a separate repository (
n8n-io/n8n-docs). Contributions to improve it are welcome. - Contribute Workflow Templates: You can submit your workflows to n8n's template library through the n8n Creator hub.
Sources: CONTRIBUTING.md:267-276