diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..1889189c33 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,159 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with +code in the n8n repository. + +## Project Overview + +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. + +## General Guidelines + +- Always use pnpm +- We use Linear as a ticket tracking system +- We use Posthog for feature flags +- When starting to work on a new ticket – create a new branch from fresh + master with the name specified in Linear ticket +- When creating a new branch for a ticket in Linear - use the branch name + suggested by linear +- Use mermaid diagrams in MD files when you need to visualise something + +## Essential Commands + +### Building +Use `pnpm build` to build all packages. ALWAYS redirect the output of the +build command to a file: + +```bash +pnpm build > build.log 2>&1 +``` + +You can inspect the last few lines of the build log file to check for errors: +```bash +tail -n 20 build.log +``` + +### Testing +- `pnpm test` - Run all tests +- `pnpm test:affected` - Runs tests based on what has changed since the last + commit +- `pnpm dev:e2e` - E2E tests in development mode + +Running a particular test file requires going to the directory of that test +and running: `pnpm test `. + +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. + +### Code Quality +- `pnpm lint` - Lint code +- `pnpm typecheck` - Run type checks + +Always 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. + +## Architecture Overview + +**Monorepo Structure:** pnpm workspaces with Turbo build orchestration + +### Package Structure + +The monorepo is organized into these key packages: + +- **`packages/@n8n/api-types`**: Shared TypeScript interfaces between frontend and backend +- **`packages/workflow`**: Core workflow interfaces and types +- **`packages/core`**: Workflow execution engine +- **`packages/cli`**: Express server, REST API, and CLI commands +- **`packages/editor-ui`**: Vue 3 frontend application +- **`packages/@n8n/i18n`**: Internationalization for UI text +- **`packages/nodes-base`**: Built-in nodes for integrations +- **`packages/@n8n/nodes-langchain`**: AI/LangChain nodes +- **`@n8n/design-system`**: Vue component library for UI consistency +- **`@n8n/config`**: Centralized configuration management + +## Technology Stack + +- **Frontend:** Vue 3 + TypeScript + Vite + Pinia + Storybook UI Library +- **Backend:** Node.js + TypeScript + Express + TypeORM +- **Testing:** Jest (unit) + Playwright (E2E) +- **Database:** TypeORM with SQLite/PostgreSQL/MySQL support +- **Code Quality:** Biome (for formatting) + ESLint + lefthook git hooks + +### Key Architectural Patterns + +1. **Dependency Injection**: Uses `@n8n/di` for IoC container +2. **Controller-Service-Repository**: Backend follows MVC-like pattern +3. **Event-Driven**: Internal event bus for decoupled communication +4. **Context-Based Execution**: Different contexts for different node types +5. **State Management**: Frontend uses Pinia stores +6. **Design System**: Reusable components and design tokens are centralized in + `@n8n/design-system`, where all pure Vue components should be placed to + ensure consistency and reusability + +## Key Development Patterns + +- Each package has isolated build configuration and can be developed independently +- Hot reload works across the full stack during development +- Node development uses dedicated `node-dev` CLI tool +- Workflow tests are JSON-based for integration testing +- AI features have dedicated development workflow (`pnpm dev:ai`) + +### TypeScript Best Practices +- **NEVER use `any` type** - use proper types or `unknown` +- **Avoid type casting with `as`** - use type guards or type predicates instead +- **Define shared interfaces in `@n8n/api-types`** package for FE/BE communication + +### Error Handling +- Don't use `ApplicationError` class in CLI and nodes for throwing errors, + because it's deprecated. Use `UnexpectedError`, `OperationalError` or + `UserError` instead. +- Import from appropriate error classes in each package + +### Frontend Development +- **All UI text must use i18n** - add translations to `@n8n/i18n` package +- **Use CSS variables directly** - never hardcode spacing as px values +- **data-test-id must be a single value** (no spaces or multiple values) + +When implementing CSS, refer to @packages/frontend/CLAUDE.md for guidelines on +CSS variables and styling conventions. + +### Testing Guidelines +- **Always work from within the package directory** when running tests +- **Mock all external dependencies** in unit tests +- **Confirm test cases with user** before writing unit tests +- **Typecheck is critical before committing** - always run `pnpm typecheck` +- **When modifying pinia stores**, check for unused computed properties + +What we use for testing and writing tests: +- For testing nodes and other backend components, we use Jest for unit tests. Examples can be found in `packages/nodes-base/nodes/**/*test*`. +- We use `nock` for server mocking +- For frontend we use `vitest` +- For e2e tests we use `Playwright` and `pnpm dev:e2e`. The old Cypress tests + are being migrated to Playwright, so please use Playwright for new tests. + +### Common Development Tasks + +When implementing features: +1. Define API types in `packages/@n8n/api-types` +2. Implement backend logic in `packages/cli` module, follow + `@packages/cli/scripts/backend-module/backend-module.guide.md` +3. Add API endpoints via controllers +4. Update frontend in `packages/editor-ui` with i18n support +5. Write tests with proper mocks +6. Run `pnpm typecheck` to verify types + +## Github Guidelines +- When creating a PR, use the conventions in + `.github/pull_request_template.md` and + `.github/pull_request_title_conventions.md`. +- Use `gh pr create --draft` to create draft PRs. +- Always reference the Linear ticket in the PR description, + use `https://linear.app/n8n/issue/[TICKET-ID]` +- always link to the github issue if mentioned in the linear ticket. diff --git a/packages/frontend/CLAUDE.md b/packages/frontend/CLAUDE.md new file mode 100644 index 0000000000..3a9f6fbd28 --- /dev/null +++ b/packages/frontend/CLAUDE.md @@ -0,0 +1,117 @@ +# CLAUDE.md + +Extra information, specific to the frontend codebase. + +### CSS Variables Reference + +Use the following CSS variables to maintain consistency across the +application. These variables cover colors, spacing, typography, and borders. + +#### Colors +```css +/* Primary Colors */ +--color-primary-shade-1 +--color-primary +--color-primary-tint-1 +--color-primary-tint-2 +--color-primary-tint-3 + +/* Secondary Colors */ +--color-secondary-shade-1 +--color-secondary +--color-secondary-tint-1 +--color-secondary-tint-3 + +/* Success Colors */ +--color-success-shade-1 +--color-success +--color-success-light +--color-success-light-2 +--color-success-tint-1 +--color-success-tint-2 + +/* Warning Colors */ +--color-warning-shade-1 +--color-warning +--color-warning-tint-1 +--color-warning-tint-2 + +/* Danger Colors */ +--color-danger-shade-1 +--color-danger +--color-danger-tint-1 +--color-danger-tint-2 + +/* Text Colors */ +--color-text-dark +--color-text-base +--color-text-light +--color-text-lighter +--color-text-xlight +--color-text-danger + +/* Foreground Colors */ +--color-foreground-xdark +--color-foreground-dark +--color-foreground-base +--color-foreground-light +--color-foreground-xlight + +/* Background Colors */ +--color-background-dark +--color-background-medium +--color-background-base +--color-background-light +--color-background-xlight +``` + +#### Spacing +```css +--spacing-5xs: 2px +--spacing-4xs: 4px +--spacing-3xs: 6px +--spacing-2xs: 8px +--spacing-xs: 12px +--spacing-s: 16px +--spacing-m: 20px +--spacing-l: 24px +--spacing-xl: 32px +--spacing-2xl: 48px +--spacing-3xl: 64px +--spacing-4xl: 128px +--spacing-5xl: 256px +``` + +#### Typography +```css +--font-size-3xs: 10px +--font-size-2xs: 12px +--font-size-xs: 13px +--font-size-s: 14px +--font-size-m: 16px +--font-size-l: 18px +--font-size-xl: 20px +--font-size-2xl: 28px + +--font-line-height-compact: 1.25 +--font-line-height-regular: 1.3 +--font-line-height-loose: 1.35 +--font-line-height-xloose: 1.5 + +--font-weight-regular: 400 +--font-weight-bold: 600 +--font-family: InterVariable, sans-serif +``` + +#### Borders +```css +--border-radius-small: 2px +--border-radius-base: 4px +--border-radius-large: 8px +--border-radius-xlarge: 12px + +--border-width-base: 1px +--border-style-base: solid +--border-base: var(--border-width-base) var(--border-style-base) var(--color-foreground-base) +``` +