<h1 align="center">
<a href="https://prompts.chat">
This file provides guidance on how to work with the n8n repository.
Sign in to like and favorite skills
This file provides guidance on how to work with the n8n repository.
n8n is a workflow automation platform written in TypeScript, using a monorepo structure managed by pnpm workspaces. It consists of a Node.js backend, Vue.js frontend, and extensible node-based workflow engine.
Use
pnpm build to build all packages. ALWAYS redirect the output of the
build command to a file:
pnpm build > build.log 2>&1
You can inspect the last few lines of the build log file to check for errors:
tail -n 20 build.log
pnpm test - Run all testspnpm test:affected - Runs tests based on what has changed since the last
commitRunning a particular test file requires going to the directory of that test and running:
pnpm test <test-file>.
When changing directories, use
pushd to navigate into the directory and
popd to return to the previous directory. When in doubt, use pwd to check
your current directory.
pnpm lint - Lint codepnpm typecheck - Run type checksAlways run lint and typecheck before committing code to ensure quality. Execute these commands from within the specific package directory you're working on (e.g.,
cd packages/cli && pnpm lint). Run the full repository
check only when preparing the final PR. When your changes affect type
definitions, interfaces in @n8n/api-types, or cross-package dependencies,
build the system before running lint and typecheck.
Monorepo Structure: pnpm workspaces with Turbo build orchestration
The monorepo is organized into these key packages:
packages/@n8n/api-types: Shared TypeScript interfaces between frontend and backendpackages/workflow: Core workflow interfaces and typespackages/core: Workflow execution enginepackages/cli: Express server, REST API, and CLI commandspackages/editor-ui: Vue 3 frontend applicationpackages/@n8n/i18n: Internationalization for UI textpackages/nodes-base: Built-in nodes for integrationspackages/@n8n/nodes-langchain: AI/LangChain nodes@n8n/design-system: Vue component library for UI consistency@n8n/config: Centralized configuration management@n8n/di for IoC container@n8n/design-system, where all pure Vue components should be placed to
ensure consistency and reusabilitynode-dev CLI toolpnpm dev:ai)The
n8n-workflow package exports graph traversal utilities from
packages/workflow/src/common/. Use these instead of custom traversal logic.
Key concept:
workflow.connections is indexed by source node.
To find parent nodes, use mapConnectionsByDestination() to invert it first.
import { getParentNodes, getChildNodes, mapConnectionsByDestination } from 'n8n-workflow'; // Finding parent nodes (predecessors) - requires inverted connections const connectionsByDestination = mapConnectionsByDestination(workflow.connections); const parents = getParentNodes(connectionsByDestination, 'NodeName', 'main', 1); // Finding child nodes (successors) - uses connections directly const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);
any type - use proper types or unknownas - use type guards or type predicates instead (except in test code where as is acceptable)@n8n/api-types package for FE/BE communicationApplicationError class in CLI and nodes for throwing errors,
because it's deprecated. Use UnexpectedError, OperationalError or
UserError instead.@n8n/i18n packageWhen implementing CSS, refer to @packages/frontend/CLAUDE.md for guidelines on CSS variables and styling conventions.
pnpm typecheckWhat we use for testing and writing tests:
packages/nodes-base/nodes/**/*test*.nock for server mockingvitestpnpm --filter=n8n-playwright test:local.
See packages/testing/playwright/README.md for details.When implementing features:
packages/@n8n/api-typespackages/cli module, follow
@packages/cli/scripts/backend-module/backend-module-guide.mdpackages/editor-ui with i18n supportpnpm typecheck to verify types.github/pull_request_template.md and
.github/pull_request_title_conventions.md.gh pr create --draft to create draft PRs.https://linear.app/n8n/issue/[TICKET-ID]