Getting Started: Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a comprehensive overview of setting up a local development environment for n8n. The project is a TypeScript-based monorepo managed with pnpm workspaces, comprising a Node.js backend, a Vue.js frontend, and an extensible node-based architecture. Following these steps will enable you to install dependencies, build the project, and start developing new features or nodes.
The setup process involves configuring prerequisites, cloning the repository, and using pnpm commands to manage the development lifecycle. This includes running the full application, developing custom nodes with hot-reloading, and executing the test suites.
Prerequisites
Before setting up the n8n repository, you must have specific versions of Node.js and pnpm installed, along with essential build tools for your operating system.
Sources: CONTRIBUTING.md:47-89
Required Tools
| Tool | Version | Installation Notes |
|---|---|---|
| Node.js | 22.16 or newer | Required for all development. |
| pnpm | 10.2 or newer | The required package manager for the monorepo. |
| corepack | N/A | Recommended for managing the pnpm version. Enable with corepack enable. |
Sources: CONTRIBUTING.md:52-64
The following diagram illustrates the relationship between the core development tools.
This diagram shows the hierarchy of required development tools.
Sources: CONTRIBUTING.md:52-71
Build Tools
Native dependencies require specific build tools depending on your operating system.
- 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 are required.
Sources: CONTRIBUTING.md:74-89
Initial Repository Setup
To begin development, you must fork and clone the repository, install all dependencies using pnpm, and perform an initial build. This process links all the local packages together as defined in the pnpm workspace.
Sources: CONTRIBUTING.md:94-122
The setup workflow follows these steps:
This flowchart outlines the one-time setup process for the n8n repository.
Sources: CONTRIBUTING.md:100-122
Step-by-Step Commands
- Fork and Clone
# Clone your fork git clone https://github.com/%3Cyour_github_username%3E/n8n.git cd n8n - Add Upstream Remote
git remote add upstream https://github.com/n8n-io/n8n.git - Install Dependencies
This command installs all dependencies for all modules in the monorepo and links them together.pnpm install - Build Project
This command compiles all TypeScript code across all packages.pnpm build
Sources: CONTRIBUTING.md:103-122
Development Cycle
n8n provides several scripts to streamline the development process, including a full-stack development server with hot-reloading and more targeted commands for specific packages to conserve system resources.
Sources: CONTRIBUTING.md:127-203
Running the Application
| Command | Description |
|---|---|
pnpm start | Starts n8n in production mode after a build. |
pnpm dev | Starts n8n in development mode. Automatically rebuilds code, restarts the backend, and refreshes the frontend on changes. |
Sources: CONTRIBUTING.md:124-132
Selective Development Commands
To improve performance, especially on resource-constrained systems, you can run only the packages relevant to your work.
This diagram shows the available filtered development commands.
Sources: CONTRIBUTING.md:162-181
Hot Reload for Nodes
When developing nodes or credentials, you can enable hot reload to see changes without restarting the entire server by setting the N8N_DEV_RELOAD environment variable.
N8N_DEV_RELOAD=true pnpm dev
This is particularly useful when working on a specific node package. You can watch the node package in one terminal and run the CLI with hot reload in another.
Sources: CONTRIBUTING.md:144-150, CONTRIBUTING.md:188-193
Custom Node Development
The n8n project provides a dedicated CLI tool, @n8n/create-node, to scaffold new community nodes with best practices.
Sources: packages/@n8n/create-node/README.md, packages/@n8n/node-cli/README.md
Scaffolding a New Node
To create a new node, run the following command and follow the interactive prompts:
npm create @n8n/node@latest
This command generates a new project directory with a standard structure for nodes and credentials.
Sources: packages/@n8n/create-node/README.md:5-9, packages/@n8n/node-cli/README.md:5-9
Node Development Workflow
The generated node project comes with its own set of npm scripts that use @n8n/node-cli internally.
This diagram illustrates the development workflow for a custom community node.
Sources: packages/@n8n/create-node/README.md:46-60, packages/@n8n/node-cli/README.md:49-62
The generated project includes the following scripts:
| Command | Description |
|---|---|
npm run dev | Runs n8n with your node in development mode with hot reload. |
npm run build | Compiles your node for distribution. |
npm run lint | Lints the node code. |
npm run release | Handles the full release process to npm. |
Sources: packages/@n8n/create-node/README.md:65-85
Testing
The n8n repository includes suites for both unit and end-to-end (E2E) testing. All tests can be run from the root directory with pnpm test, or from within a specific package to run only its tests.
Sources: CONTRIBUTING.md:246-253, AGENTS.md:58-62
Unit Tests
Unit tests are written with Jest and can be found in test/ or __tests__/ directories.
- Command:
pnpm testorpnpm test <test-file> - Mocking:
nockis used for server mocking andjest-mock-extendedfor mocking interfaces. All external dependencies should be mocked.
Sources: AGENTS.md:124-126, packages/nodes-base/TESTING_PROMPT.md:19-21, CONTRIBUTING.md:248-253
End-to-End (E2E) Tests
E2E tests are built with Playwright and are located in the packages/testing/playwright directory.
- Run locally:
pnpm --filter=n8n-playwright test:local - Run with UI mode:
pnpm --filter=n8n-playwright test:local --ui - Run specific tests:
pnpm --filter=n8n-playwright test:local --grep="test-name"
Sources: CONTRIBUTING.md:261-266
The E2E testing architecture follows a four-layer pattern to ensure separation of concerns and maintainability.
This diagram shows the four-layer architecture for UI testing with Playwright.
Sources: packages/testing/playwright/CONTRIBUTING.md:36-42
Code Quality
Before committing any code, it is essential to run linting and type-checking to ensure code quality and consistency.
- Linting:
pnpm lint - Type Checking:
pnpm typecheck
These commands should be executed from within the specific package directory you are working on (e.g., cd packages/cli && pnpm lint).
Sources: AGENTS.md:64-73