/mrge-io/eval-n8n

Wiki directory

Browse AI-generated documentation for any repository.

Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

n8n is a workflow automation platform that allows for the creation of complex automations by connecting various services. It features a monorepo structure managed by pnpm workspaces, with a Node.js backend, a Vue.js frontend, and an extensible node-based engine. This guide provides a comprehensive overview for setting up a local development environment, running n8n using Docker, and creating custom nodes.

This document covers the initial setup, development cycle, testing procedures, and extension capabilities. For more detailed information on specific topics, refer to the Node Development Guide and Testing Guide.

Development Setup

To contribute to n8n or run it locally for development, you must set up the project on your local machine. The following sections outline the prerequisites and the setup process.

Sources: CONTRIBUTING.md, CLAUDE.md

Prerequisites

Before setting up the n8n repository, ensure your development environment meets the following requirements.

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. It is recommended to install it via `corepack`.
corepack	(Bundled with Node.js)	Enable with `corepack enable` and install the correct pnpm version with `corepack prepare --activate`.
Build Tools	-	`build-essential` and `python` on Debian/Ubuntu, or `windows-build-tools` on Windows.

Sources: CONTRIBUTING.md:37-78

Repository Setup

The following diagram and steps describe how to clone and build the project.

Generating architecture diagram...

This diagram shows the sequence of commands to set up the n8n development environment.
Sources: CONTRIBUTING.md:81-108, CLAUDE.md:19-25

Fork and Clone: Fork the n8n-io/n8n repository on GitHub and clone your fork locally.
```
git clone https://github.com/%3Cyour_github_username%3E/n8n.git
cd n8n
```
Add Upstream: Add the original n8n repository as the upstream remote to keep your fork updated.
```
git remote add upstream https://github.com/n8n-io/n8n.git
```
Install Dependencies: Install all dependencies and link the monorepo packages together.
```
pnpm install
```
Build Project: Compile all packages in the monorepo.
```
pnpm build
```

Sources: CONTRIBUTING.md:81-108

Running n8n

Once the setup is complete, you can start the n8n application in different modes.

Command	Description
`pnpm start`	Starts n8n in production mode. Requires a build (`pnpm build`) first.
`pnpm dev`	Starts n8n in development mode with hot-reloading for both frontend and backend.
`pnpm dev:be`	Starts only the backend in development mode.
`pnpm dev:fe`	Starts the frontend development server and a backend server.
`pnpm dev:ai`	Runs only essential packages for AI/LangChain node development.

To enable hot reload for nodes, use the N8N_DEV_RELOAD environment variable:

N8N_DEV_RELOAD=true pnpm dev

Sources: CONTRIBUTINGmd:113-160

Using Docker

For a containerized setup, n8n can be run using Docker. This is a convenient way to manage the application and its data without a full local development environment.

Sources: docker/images/n8n/README.md

Basic Docker Start

The following command creates a Docker volume for persistent storage and starts the n8n container.

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

After running the command, n8n will be accessible at http://localhost:5678. The /home/node/.n8n directory, which contains the SQLite database and credential encryption key, is persisted in the n8n_data volume.

Sources: docker/images/n8n/README.md:52-62

Tunneling with Docker

For development involving webhooks, n8n can be started with a tunnel service that exposes your local instance to the internet.

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n \
 start --tunnel

Warning: This is for development and testing only and should not be used in production.

Sources: docker/images/n8n/README.md:69-80

Using PostgreSQL with Docker

By default, n8n uses SQLite. To use a PostgreSQL database, you must configure the appropriate environment variables.

The following diagram illustrates the startup flow with PostgreSQL.

Generating architecture diagram...

This diagram shows how the n8n Docker container decides which database to use based on environment variables.
Sources: docker/images/n8n/README.md:82-104

Environment Variable	Description
`DB_TYPE`	Set to `postgresdb` to enable PostgreSQL.
`DB_POSTGRESDB_HOST`	The hostname of the PostgreSQL server.
`DB_POSTGRESDB_PORT`	The port of the PostgreSQL server.
`DB_POSTGRESDB_DATABASE`	The database name.
`DB_POSTGRESDB_USER`	The username for the database.
`DB_POSTGRESDB_PASSWORD`	The password for the database user.
`DB_POSTGRESDB_SCHEMA`	The database schema to use.

These variables also support file-based secrets by appending _FILE to the variable name (e.g., DB_POSTGRESDB_PASSWORD_FILE).

Sources: docker/images/n8n/README.md:82-114

Create Custom Nodes

n8n is extensible, and you can create your own custom nodes using the @n8n/create-node scaffolding tool.

Sources: packages/@n8n/create-node/README.md, packages/@n8n/node-cli/README.md

Scaffolding a New Node

To create a new node, run the interactive CLI command:

npm create @n8n/node@latest

The CLI will prompt for the node name, type (HTTP API or from scratch), API base URL, and authentication type. It generates a project structure with all necessary files.

The generated project structure is as follows:

my-awesome-api-node/
├── src/
│   ├── nodes/
│   │   └── MyAwesomeApi/
│   │       ├── MyAwesomeApi.node.ts    # Main node logic
│   │       └── MyAwesomeApi.node.json  # Node metadata
│   └── credentials/
│       └── MyAwesomeApiAuth.credentials.ts
├── package.json
├── tsconfig.json
└── README.md

Sources: packages/@n8n/create-node/README.md:5-52, 126-143

Node Development Workflow

The following sequence diagram illustrates the development and release process for a custom node.

Generating architecture diagram...

This diagram shows the developer's interaction with the CLI to develop, build, and publish a custom node.
Sources: packages/@n8n/create-node/README.md:54-124, packages/@n8n/node-cli/README.md:10-30

The generated project includes several npm scripts to manage the development lifecycle:

Command	Description	Underlying CLI Command
`npm run dev`	Starts n8n with your node in development mode and hot-reloading.	`n8n-node dev`
`npm run build`	Compiles the node for production.	`n8n-node build`
`npm run lint`	Lints the code for style and convention issues.	`n8n-node lint`
`npm run release`	Handles the full release process, including versioning and publishing to npm.	`n8n-node release`

Sources: packages/@n8n/create-node/README.md:73-102, packages/@n8n/node-cli/READMEmd:10-30

Testing

The repository includes a comprehensive testing suite using Jest for unit tests and Playwright for end-to-end (E2E) tests.

Sources: CONTRIBUTING.md:239-270, packages/testing/playwright/CONTRIBUTING.md

Unit Tests

Unit tests are written with Jest and can be run from the root of the monorepo or within a specific package.

# Run all tests in the repository
pnpm test

# Run tests for a specific package
cd packages/cli
pnpm test

Sources: CONTRIBUTING.md:241-249

End-to-End (E2E) Tests

E2E tests use Playwright and follow a structured, four-layer architecture for UI testing to ensure separation of concerns.

Generating architecture diagram...

This diagram illustrates the four-layer architecture for UI testing with Playwright.
Sources: packages/testing/playwright/CONTRIBUTING.md:32-40

To run E2E tests, first configure your local environment by adding a .vscode/settings.json file:

{
  "playwright.env": {
    "N8N_BASE_URL": "http://localhost:5679",
    "SHOW_BROWSER": "true",
    "RESET_E2E_DB": "true"
  }
}

You can then run tests using the "Playwright Test for VSCode" extension or via CLI commands.

Sources: packages/testing/playwright/CONTRIBUTING.md:10-19

There is also a separate workflow testing framework that uses Playwright to execute workflows and validate their output schemas against snapshots. This is useful for detecting regressions and breaking changes in external APIs.

Key commands for workflow testing:

pnpm test:workflows: Runs all active workflows and checks for execution errors.
SCHEMA=true pnpm test:workflows: Runs workflows and validates their output against a saved JSON schema.
pnpm test:workflows --update-snapshots: Updates the saved schema snapshots.

Sources: packages/testing/playwright/tests/cli-workflows/README.md:22-38

Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

Development Setup

To contribute to n8n or run it locally for development, you must set up the project on your local machine. The following sections outline the prerequisites and the setup process.

Sources: CONTRIBUTING.md, CLAUDE.md

Prerequisites

Before setting up the n8n repository, ensure your development environment meets the following requirements.

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. It is recommended to install it via `corepack`.
corepack	(Bundled with Node.js)	Enable with `corepack enable` and install the correct pnpm version with `corepack prepare --activate`.
Build Tools	-	`build-essential` and `python` on Debian/Ubuntu, or `windows-build-tools` on Windows.

Sources: CONTRIBUTING.md:37-78

Repository Setup

The following diagram and steps describe how to clone and build the project.

Generating architecture diagram...

This diagram shows the sequence of commands to set up the n8n development environment.
Sources: CONTRIBUTING.md:81-108, CLAUDE.md:19-25

Fork and Clone: Fork the n8n-io/n8n repository on GitHub and clone your fork locally.
```
git clone https://github.com/%3Cyour_github_username%3E/n8n.git
cd n8n
```
Add Upstream: Add the original n8n repository as the upstream remote to keep your fork updated.
```
git remote add upstream https://github.com/n8n-io/n8n.git
```
Install Dependencies: Install all dependencies and link the monorepo packages together.
```
pnpm install
```
Build Project: Compile all packages in the monorepo.
```
pnpm build
```

Sources: CONTRIBUTING.md:81-108

Running n8n

Once the setup is complete, you can start the n8n application in different modes.

Command	Description
`pnpm start`	Starts n8n in production mode. Requires a build (`pnpm build`) first.
`pnpm dev`	Starts n8n in development mode with hot-reloading for both frontend and backend.
`pnpm dev:be`	Starts only the backend in development mode.
`pnpm dev:fe`	Starts the frontend development server and a backend server.
`pnpm dev:ai`	Runs only essential packages for AI/LangChain node development.

To enable hot reload for nodes, use the N8N_DEV_RELOAD environment variable:

N8N_DEV_RELOAD=true pnpm dev

Sources: CONTRIBUTINGmd:113-160

Using Docker

For a containerized setup, n8n can be run using Docker. This is a convenient way to manage the application and its data without a full local development environment.

Sources: docker/images/n8n/README.md

Basic Docker Start

The following command creates a Docker volume for persistent storage and starts the n8n container.

docker volume create n8n_data

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n

Sources: docker/images/n8n/README.md:52-62

Tunneling with Docker

For development involving webhooks, n8n can be started with a tunnel service that exposes your local instance to the internet.

docker run -it --rm \
 --name n8n \
 -p 5678:5678 \
 -v n8n_data:/home/node/.n8n \
 docker.n8n.io/n8nio/n8n \
 start --tunnel

Warning: This is for development and testing only and should not be used in production.

Sources: docker/images/n8n/README.md:69-80

Using PostgreSQL with Docker

By default, n8n uses SQLite. To use a PostgreSQL database, you must configure the appropriate environment variables.

The following diagram illustrates the startup flow with PostgreSQL.

Generating architecture diagram...

This diagram shows how the n8n Docker container decides which database to use based on environment variables.
Sources: docker/images/n8n/README.md:82-104

Environment Variable	Description
`DB_TYPE`	Set to `postgresdb` to enable PostgreSQL.
`DB_POSTGRESDB_HOST`	The hostname of the PostgreSQL server.
`DB_POSTGRESDB_PORT`	The port of the PostgreSQL server.
`DB_POSTGRESDB_DATABASE`	The database name.
`DB_POSTGRESDB_USER`	The username for the database.
`DB_POSTGRESDB_PASSWORD`	The password for the database user.
`DB_POSTGRESDB_SCHEMA`	The database schema to use.

These variables also support file-based secrets by appending _FILE to the variable name (e.g., DB_POSTGRESDB_PASSWORD_FILE).

Sources: docker/images/n8n/README.md:82-114

Create Custom Nodes

n8n is extensible, and you can create your own custom nodes using the @n8n/create-node scaffolding tool.

Sources: packages/@n8n/create-node/README.md, packages/@n8n/node-cli/README.md

Scaffolding a New Node

To create a new node, run the interactive CLI command:

npm create @n8n/node@latest

The CLI will prompt for the node name, type (HTTP API or from scratch), API base URL, and authentication type. It generates a project structure with all necessary files.

The generated project structure is as follows:

my-awesome-api-node/
├── src/
│   ├── nodes/
│   │   └── MyAwesomeApi/
│   │       ├── MyAwesomeApi.node.ts    # Main node logic
│   │       └── MyAwesomeApi.node.json  # Node metadata
│   └── credentials/
│       └── MyAwesomeApiAuth.credentials.ts
├── package.json
├── tsconfig.json
└── README.md

Sources: packages/@n8n/create-node/README.md:5-52, 126-143

Node Development Workflow

The following sequence diagram illustrates the development and release process for a custom node.

Generating architecture diagram...

This diagram shows the developer's interaction with the CLI to develop, build, and publish a custom node.
Sources: packages/@n8n/create-node/README.md:54-124, packages/@n8n/node-cli/README.md:10-30

The generated project includes several npm scripts to manage the development lifecycle:

Command	Description	Underlying CLI Command
`npm run dev`	Starts n8n with your node in development mode and hot-reloading.	`n8n-node dev`
`npm run build`	Compiles the node for production.	`n8n-node build`
`npm run lint`	Lints the code for style and convention issues.	`n8n-node lint`
`npm run release`	Handles the full release process, including versioning and publishing to npm.	`n8n-node release`

Sources: packages/@n8n/create-node/README.md:73-102, packages/@n8n/node-cli/READMEmd:10-30

Testing

The repository includes a comprehensive testing suite using Jest for unit tests and Playwright for end-to-end (E2E) tests.

Sources: CONTRIBUTING.md:239-270, packages/testing/playwright/CONTRIBUTING.md

Unit Tests

Unit tests are written with Jest and can be run from the root of the monorepo or within a specific package.

# Run all tests in the repository
pnpm test

# Run tests for a specific package
cd packages/cli
pnpm test

Sources: CONTRIBUTING.md:241-249

End-to-End (E2E) Tests

E2E tests use Playwright and follow a structured, four-layer architecture for UI testing to ensure separation of concerns.

Generating architecture diagram...

This diagram illustrates the four-layer architecture for UI testing with Playwright.
Sources: packages/testing/playwright/CONTRIBUTING.md:32-40

To run E2E tests, first configure your local environment by adding a .vscode/settings.json file:

{
  "playwright.env": {
    "N8N_BASE_URL": "http://localhost:5679",
    "SHOW_BROWSER": "true",
    "RESET_E2E_DB": "true"
  }
}

You can then run tests using the "Playwright Test for VSCode" extension or via CLI commands.

Sources: packages/testing/playwright/CONTRIBUTING.md:10-19

Key commands for workflow testing:

pnpm test:workflows: Runs all active workflows and checks for execution errors.
SCHEMA=true pnpm test:workflows: Runs workflows and validates their output against a saved JSON schema.
pnpm test:workflows --update-snapshots: Updates the saved schema snapshots.

Sources: packages/testing/playwright/tests/cli-workflows/README.md:22-38