Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
n8n uses a monorepo architecture to manage multiple modules, including the backend server, frontend UI, and a library of workflow nodes. The project utilizes pnpm workspaces and Turbo to orchestrate builds, manage dependencies, and handle inter-module linking.
Sources: CONTRIBUTING.md:71-73, AGENTS.md:10-14, AGENTS.md:123-125
Workspace Architecture
The monorepo organizes code into distinct packages within the /packages directory. Each package maintains its own configuration but relies on a shared pnpm workspace setup to automatically link local dependencies.
This diagram illustrates the high-level relationship and dependency flow between major modules in the n8n monorepo.
Sources: CONTRIBUTING.md:71-89, AGENTS.md:127-142
Key Package Categories
| Package Path | Purpose | Key Technologies |
|---|---|---|
packages/cli | Express server, REST API, and CLI entry point. | Node.js, Express, TypeORM |
packages/core | Workflow execution engine and node logic. | TypeScript, @n8n/di |
packages/workflow | Shared core interfaces and types. | TypeScript |
packages/frontend/editor-ui | Vue 3 workflow editor and user interface. | Vue 3, Vite, Pinia |
packages/nodes-base | Library of built-in integration nodes. | TypeScript |
packages/frontend/@n8n/design-system | Reusable Vue components and CSS variables. | Vue 3, SCSS, Storybook |
packages/quality/testing/playwright | End-to-end and UI testing suite. | Playwright, TypeScript |
Sources: CONTRIBUTING.md:76-89, AGENTS.md:127-142, packages/frontend/@n8n/design-system/README.md:1-10
Dependency Management
n8n uses pnpm to facilitate module management and version consistency. The project employs specific protocols to handle internal and external dependencies:
- Workspace Protocol (
workspace:*): Resolves dependencies to the local version within the monorepo. - Catalog Protocol (
catalog:<name>): Centralizes external dependency versions (e.g.,vue) to ensure all packages use the same version of a library. - Virtual Stores:
pnpmmanages physical copies of libraries in a.pnpmvirtual store to minimize duplication.
Sources: CONTRIBUTING.md:107-113, packages/frontend/@n8n/design-system/README.md:27-35, packages/quality/policy/code-health/src/single-instance/explain-duplicates.ts:88-95
Build and Development Workflow
Build orchestration is handled by Turbo, which recognizes the dependency graph between packages.
- Full Build: Running
pnpm buildfrom the root executes the build task across all modules in the correct order. - Selective Development: Developers use filtered commands like
pnpm dev:be(backend-only) orpnpm dev:fe:editor(frontend-only) to reduce resource consumption. - Hot Reload: The backend server supports
N8N_DEV_RELOAD=trueto watch for node file changes without requiring a full restart.
Sources: CONTRIBUTING.md:144-147, CONTRIBUTING.md:179-200, CONTRIBUTING.md:247-254
Testing Infrastructure
The testing suite is partitioned by scope and package:
- Unit Tests: Handled by Vitest within individual package directories.
- E2E/UI Tests: Located in
packages/quality/testing/playwright, using a four-layer approach: Tests, Composables, Page Objects, and BasePage. - Static Analysis: CI runs
@n8n/code-healthto enforce monorepo rules, dependency hygiene, and encryption boundaries.
Sources: CONTRIBUTING.md:520-524, AGENTS.md:241-246, packages/quality/testing/playwright/CONTRIBUTING.md:33-40
Package Convention: Custom Nodes
Community nodes and core nodes follow a standardized internal structure to remain compatible with the n8n CLI and execution engine.
{
"name": "n8n-nodes-example",
"n8n": {
"n8nNodesApiVersion": 1,
"credentials": [
"dist/credentials/Example.credentials.js"
],
"nodes": [
"dist/nodes/Example/Example.node.js"
]
}
}
The package.json for node modules includes an n8n block that specifies the entry points for transpiled JavaScript files.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:46-64, packages/nodes-base/AGENTS.md:92-105