Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The n8n project is a workflow automation platform developed within a monorepo. This structure facilitates code sharing, centralized dependency management, and streamlined development across its various components, including a Node.js backend, a Vue.js frontend, and an extensible node-based engine. The entire codebase is written in TypeScript.
The monorepo is managed using pnpm workspaces for dependency and module management, with Turbo for build orchestration. This setup allows for isolated package development, hot reloading across the stack, and efficient testing and code quality checks.
Sources: CLAUDE.md:5-8, CONTRIBUTING.md:21-22, CLAUDE.md:50-51
Tooling and Orchestration
The monorepo relies on a specific set of tools to manage its complexity, handle dependencies, and orchestrate builds and development tasks.
Sources: CONTRIBUTING.md:37-58, CLAUDE.md:11-48
pnpm Workspaces
pnpm workspaces are used to manage the multiple modules within the repository. This system automatically creates file-links between modules that depend on each other, which is crucial for a cohesive development experience. The pnpm-workspace.yaml file (not present in the provided context, but its use is documented) defines the paths to the packages included in the workspace. The recommended way to manage pnpm is by enabling Node.js corepack.
Sources: CONTRIBUTING.md:46-49, CONTRIBUTING.md:50-52
Build System
The project uses pnpm scripts to handle building, testing, and linting. Key commands are executed from the root directory to manage the entire monorepo.
| Command | Description |
|---|---|
pnpm install | Installs all dependencies for all modules and links them. |
pnpm build | Builds all packages. Build output should be redirected to a log file. |
pnpm dev | Starts a development server that automatically rebuilds code, restarts the backend, and refreshes the frontend on changes. |
pnpm test | Runs all unit tests across all packages. |
pnpm lint | Lints the code in a specific package. |
pnpm typecheck | Runs TypeScript type checks. |
Sources: CONTRIBUTING.md:83-89, CLAUDE.md:13-48
For more efficient development, selective commands are available to run only relevant parts of the application:
pnpm dev:be: For backend-only development.pnpm dev:fe: For frontend-only development.pnpm dev:ai: For AI/LangChain node development.
Sources: CONTRIBUTING-md:123-139
Package Architecture
The monorepo is organized into several key packages, each with a distinct responsibility. This modular structure promotes separation of concerns and reusability.
Sources: CLAUDE.md:53-68, CONTRIBUTING.md:24-35
The following diagram illustrates the high-level relationship between the main packages.
This diagram shows the dependencies and interactions between frontend, backend, node, and shared packages.
Sources: CLAUDE.md:53-68, CONTRIBUTING.md:24-35
Key Packages
| Package | Description |
|---|---|
packages/@n8n/api-types | Contains shared TypeScript interfaces used by both the frontend and backend. |
packages/workflow | Defines core workflow interfaces and types. |
packages/core | The core workflow execution engine. |
packages/cli | Contains the Express.js server, REST API, and command-line interface (CLI) commands. |
packages/frontend/editor-ui | The main Vue 3 frontend application for the workflow editor. |
packages/@n8n/design-system | A Vue component library for UI consistency. |
packages/@n8n/i18n | Manages internationalization and localization for UI text. |
packages/nodes-base | Contains all the built-in nodes for various services and integrations. |
packages/@n8n/nodes-langchain | Home for AI and LangChain-related nodes. |
packages/@n8n/config | Provides centralized configuration management. |
packages/node-dev | A CLI tool to create new n8n nodes. |
Sources: CLAUDE.md:57-68, CONTRIBUTING.md:26-35
Node and Credential Structure
Custom nodes are a core part of n8n's extensibility. The monorepo provides a clear structure and tooling for creating new nodes.
Node Definition
Each node consists of two main files:
- A
.node.tsfile: Contains the programmatic logic, including operations, methods, and API requests. - A
.node.jsonfile: Contains metadata for the node, such as its name, categories, and links to documentation.
For example, the GitHub node is defined in packages/nodes-base/nodes/Github/Github.node.ts and its metadata is in packages/nodes-base/nodes/Github/Github.node.json.
Sources: packages/nodes-base/nodes/Github/Github.node.ts, packages/nodes-base/nodes/Github/Github.node.json, packages/@n8n/create-node/README.md:111-117
Here is an example of the metadata structure from Github.node.json:
{
"node": "n8n-nodes-base.github",
"nodeVersion": "1.0",
"codexVersion": "1.0",
"categories": ["Development"],
"resources": {
"credentialDocumentation": [
{
"url": "https://docs.n8n.io/integrations/builtin/credentials/github/"
}
],
"primaryDocumentation": [
{
"url": "https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.github/"
}
]
}
}
Sources: packages/nodes-base/nodes/Github/Github.node.json:1-18
Node Creation
The @n8n/create-node package is a scaffolding tool to quickly generate new community nodes. It provides an interactive CLI to set up a new node project with a predefined structure.
The typical workflow for creating a new node is as follows:
This diagram shows the steps from scaffolding a new node to publishing it.
Sources: packages/@n8n/create-node/README.md:5-8, packages/@n8n/create-node/README.md:70-80
The generated project structure is standardized:
my-awesome-api-node/
├── src/
│ ├── nodes/
│ │ └── MyAwesomeApi/
│ │ ├── MyAwesomeApi.node.ts
│ │ └── MyAwesomeApi.node.json
│ └── credentials/
│ └── MyAwesomeApiAuth.credentials.ts
├── package.json
├── tsconfig.json
└── README.md
The package.json of a node package contains a special n8n section to declare its nodes and credentials.
Sources: packages/@n8n/create-node/README.md:111-122, packages/@n8n/create-node/READMEmd:126-137
Testing Structure
The monorepo includes a comprehensive testing strategy covering unit, integration, and end-to-end (E2E) tests.
*Sources: CLAUDE.md:120-131, CONTRIBUTING.md:213-241 *
Unit and E2E Testing
- Backend/Nodes: Unit tests are written with Jest.
- Frontend: Unit tests are written with Vitest.
- E2E: End-to-end tests are written using Playwright. The project is migrating from older Cypress tests to Playwright.
Sources: CLAUDE.md:124-131, CONTRIBUTING.md:214-241
Playwright E2E Test Architecture
The Playwright test suite follows a four-layer architecture to ensure separation of concerns and maintainability.
This diagram shows the four-layer architecture for UI testing with Playwright.
- Tests (
*.spec.ts): Contain high-level, readable scenarios that describe business workflows. - Composables (
*Composer.ts): Orchestrate complex, multi-step business workflows that span multiple pages. - Page Objects (
*Page.ts): Encapsulate UI interactions and element locators for a specific page. - BasePage: Provides common, reusable utility methods for interacting with the UI.
Sources: packages/testing/playwright/CONTRIBUTING.md:30-44
Conclusion
The n8n monorepo is a well-structured project that leverages pnpm workspaces to manage its modular architecture. This design separates concerns between the backend, frontend, and the extensible node system, while shared packages promote code reuse. Tooling like @n8n/create-node and a layered testing strategy with Playwright further enhance developer productivity and ensure code quality, making the platform robust and scalable.
Sources: CLAUDE.md:5-8, CONTRIBUTING.md:21-35