N8n:conventions

📚 Full Documentation:

• General: /AGENTS.md - Architecture, commands, workflows
• Frontend: /packages/frontend/AGENTS.md - CSS variables, timing

Use this skill when you need quick reminders on critical patterns.

Critical Rules (Must Follow)

Technical writing (comments, PRs, issues, docs):

• Write in ASD-STE100 Simplified Technical English: short sentences, the active voice, one instruction for each sentence

TypeScript:

• Never any → use unknown
• Prefer satisfies over as (except tests)
• Shared types in @n8n/api-types

Error Handling:

Frontend:

• Vue 3 Composition API (<script setup lang="ts">)
• CSS variables (never hardcode px) - see /packages/frontend/AGENTS.md
• All text via i18n ($t('key'))
• data-testid for E2E (single value, no spaces)

Backend:

• Controller → Service → Repository
• Dependency injection via @n8n/di
• Config via @n8n/config
• Zod schemas for validation
• Pagination args: use offset + limit in controllers and services; translate to TypeORM skip/take only inside repositories

Testing:

• Vitest (unit), Playwright (E2E)
• Mock external dependencies
• Keep filesystem tests in a test-owned temporary directory
• Set N8N_USER_FOLDER before importing settings code
• Trace branches activated by mocks and isolate every reachable mutation
• Work from package directory: pushd packages/cli && pnpm test

Database:

• SQLite/PostgreSQL only (app DB)
• Exception: DB nodes (MySQL Node, etc.) can use DB-specific features

GitHub Workflows:

• Every workflow declares a least-privilege top-level permissions: block (usually contents: read); jobs needing more override at job level

Commands:

Secrets: pnpm command lines may be recorded verbatim (opt-in dev metrics) — pass sensitive values via env vars, never inline on the command line.

Key Packages

Common Patterns

Pinia Store:

Vue Component:

Service:

📖 Need more details? Read /AGENTS.md and /packages/frontend/AGENTS.md