Welcome to n8n
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- CONTRIBUTING.md
- README.md
- docker/images/n8n/README.md
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/notification.ts
- packages/@n8n/create-node/README.md
- packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
- packages/nodes-base/AGENTS.md
- packages/nodes-base/nodes/Airtable/Airtable.node.json
- packages/nodes-base/nodes/Cron/Cron.node.json
- packages/nodes-base/nodes/GraphQL/GraphQL.node.json
- packages/nodes-base/nodes/Github/Github.node.json
- packages/nodes-base/nodes/HttpRequest/HttpRequest.node.json
- packages/nodes-base/nodes/Slack/Slack.node.json
- packages/nodes-base/nodes/Webhook/Webhook.node.json
- packages/testing/playwright/AI-TEST-CHEAT-SHEET.md
- packages/testing/playwright/CONTRIBUTING.md
- packages/testing/playwright/tests/ui/29-templates.spec.ts
n8n is a workflow automation platform designed for technical teams, combining the flexibility of code with the speed of a visual, no-code interface. It allows users to build powerful automations with over 400 integrations, native AI capabilities, and a fair-code license that provides full control over data and deployments. The name "n8n" is short for "nodemation" and is pronounced "n-eight-n".
The platform is built on a node-based architecture where users connect different services and logic blocks to create complex workflows. It is source-available, self-hostable, and extensible, allowing developers to add their own custom nodes and functionality.
Sources: README.md:3-6, README.md:46-48
Key Capabilities
- Code When You Need It: Write JavaScript/Python, add npm packages, or use the visual interface.
- AI-Native Platform: Build AI agent workflows based on LangChain with your own data and models.
- Full Control: Self-host with a fair-code license or use the cloud offering.
- Enterprise-Ready: Features advanced permissions, SSO, and air-gapped deployments.
- Active Community: Access 400+ integrations and 900+ ready-to-use templates.
Sources: README.md:10-16, docker/images/n8n/README.md:8-14
Getting Started
You can run n8n using either npx for a quick trial or Docker for a more persistent setup.
| Method | Command | Description |
|---|---|---|
| npx | npx n8n | Instantly starts n8n. Requires Node.js. |
| Docker | docker run -it --rm --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n | Deploys n8n in a Docker container. The -v flag mounts a volume to persist workflow data. |
After starting, the editor is accessible at http://localhost:5678.
Sources: README.md:20-26, docker/images/n8n/README.md:32-38
Database Configuration
By default, n8n uses an SQLite database to store workflows, credentials, and execution data. For production environments, PostgreSQL is also supported. When using an external database, it is still critical to persist the /home/node/.n8n directory, as it contains the encryption key for credentials.
To use PostgreSQL, you must set several environment variables:
DB_TYPE=postgresdbDB_POSTGRESDB_DATABASEDB_POSTGRESDB_HOSTDB_POSTGRESDB_PORTDB_POSTGRESDB_USERDB_POSTGRESDB_PASSWORDDB_POSTGRESDB_SCHEMA
Sources: docker/images/n8n/README.md:45-66
Architecture Overview
n8n is a monorepo managed by pnpm workspaces, written in TypeScript. It comprises a Node.js backend, a Vue.js frontend, and an extensible node-based workflow engine.
Sources: AGENTS.md:5-8, CONTRIBUTING.md:20-22
Monorepo Package Structure
The project is organized into several key packages that separate concerns between the frontend, backend, and core logic.
This diagram shows the high-level organization of the n8n monorepo.
| Package | Description |
|---|---|
packages/@n8n/api-types | Contains shared TypeScript interfaces used by both frontend and backend. |
packages/workflow | Defines core workflow interfaces and types. |
packages/core | The core workflow execution engine. |
packages/cli | The Express.js server, REST API, and command-line interface. |
packages/editor-ui | The Vue 3 frontend application for the workflow editor. |
packages/nodes-base | Contains all the built-in integration nodes. |
@n8n/design-system | A Vue component library for UI consistency. |
Sources: AGENTS.md:40-53, CONTRIBUTING.md:25-35
Technology Stack
- Backend: Node.js, TypeScript, Express, TypeORM
- Frontend: Vue 3, TypeScript, Vite, Pinia
- Database: SQLite, PostgreSQL, MySQL (via TypeORM)
- Testing: Jest (unit), Playwright (E2E)
- Tooling: pnpm, Turbo, Biome, ESLint
Sources: AGENTS.md:55-60
Core Concepts: Workflows and Nodes
The fundamental components of n8n are Workflows and Nodes. A workflow is a series of connected nodes that automate a process. Nodes are the individual building blocks that perform specific actions, such as triggering a workflow, making an API call, or sending a notification.
An illustrative example is the "API Fundamentals" tutorial, which models an API interaction like ordering from a restaurant.
- The HTTP Request node acts as the "Customer" making a request.
- The Webhook node acts as the "Kitchen" (server) that receives the request and provides a response.
- The API itself is the "Menu and Waiter," defining the rules of communication.
This sequence diagram shows the interaction between a client (HTTP Request node) and a server (Webhook node) in a simple GET request.
Node Categories
Nodes are organized into categories based on their function.
| Category | Examples |
|---|---|
| Core Nodes | Cron, Webhook, HTTP Request |
| Development | GitHub, GraphQL, HTTP Request |
| Communication | Slack, Telegram |
| Data & Storage | Airtable, Google Sheets, MySQL |
| HITL (Human in the Loop) | Slack (for approvals) |
Sources: packages/nodes-base/nodes/Cron/Cron.node.json:5, packages/nodes-base/nodes/Github/Github.node.json:5, packages/nodes-base/nodes/Slack/Slack.node.json:5, packages/nodes-base/nodes/Airtable/Airtable.node.json:5
Development and Contribution
The project requires Node.js v22.16+ and pnpm v10.2+. The recommended way to manage pnpm is via corepack.
Sources: CONTRIBUTING.md:46-52
Development Setup
- Fork and clone the repository.
- Install dependencies:
pnpm install - Build all packages:
pnpm build - Start development server:
pnpm dev
The pnpm dev command starts a hot-reloading environment for both the backend and frontend. For more focused development, filtered commands like pnpm dev:be (backend-only) and pnpm dev:fe (frontend-only) are available.
Sources: CONTRIBUTING.md:78-98, CONTRIBUTING.md:104-124
Essential Commands
| Command | Description |
|---|---|
pnpm build | Builds all packages in the monorepo. |
pnpm dev | Starts the full-stack development server with hot-reloading. |
pnpm start | Starts n8n in production mode after a build. |
pnpm test | Runs all unit tests. |
pnpm lint | Lints the codebase for quality checks. |
pnpm typecheck | Runs TypeScript type checks across the project. |
Sources: AGENTS.md:19-33, AGENTS.md:40-45, CONTRIBUTING.md:100-113
Creating Custom Nodes
You can extend n8n by creating your own nodes using the @n8n/create-node scaffolding tool.
npm create @n8n/node@latest
This command initiates an interactive setup process to create a new node package with a development server, build tools, and linting configured. It supports both declarative (JSON-based) and programmatic (TypeScript-based) node creation.
Sources: packages/@n8n/create-node/README.md:5-11, packages/@n8n/create-node/README.md:113-119
Testing
n8n uses Jest for unit tests and Playwright for end-to-end (E2E) tests.
- Unit Tests: Run with
pnpm test. These are located within each package. - E2E Tests: Run with
pnpm --filter=n8n-playwright test:local.
Sources: CONTRIBUTING.md:188-191, CONTRIBUTING.md:199-206
Playwright Test Architecture
The E2E testing framework follows a four-layer architecture to promote separation of concerns and reusability.
This diagram illustrates the layered architecture for UI testing with Playwright.
*Tests (.spec.ts)**: Define high-level test scenarios.
- Composables (
*Composer.ts): Orchestrate complex, multi-page business workflows. - Page Objects (
*Page.ts): Encapsulate UI elements and simple interactions for a specific page. - BasePage: Provides common, reusable utility methods like
clickByTestId.
Sources: packages/testing/playwright/CONTRIBUTING.md:32-44, packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:100-108
Licensing
n8n is fair-code licensed, not open-source. The code is distributed under two main licenses:
- Sustainable Use License: Governs the use of the community edition.
- n8n Enterprise License: For enterprise-specific features.
The source code is publicly available, and the software is self-hostable and extensible.
Sources: README.md:36-44