n8n-conventions

name n8n:conventions description Quick reference for n8n patterns. Full docs /AGENTS.md n8n Quick Reference 📚 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: import { UnexpectedError } from 'n8n-workflow' ; throw new UnexpectedError ( 'message' , { extra : { context } }); // DON'T use deprecated ApplicationError 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 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: pnpm build > build.log 2>&1 # Always redirect pnpm typecheck # Before commit pnpm lint # Before commit 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 Package Purpose packages/cli Backend API packages/frontend/editor-ui Vue 3 frontend packages/@n8n/api-types Shared types packages/@n8n/db TypeORM entities packages/workflow Core interfaces Common Patterns Pinia Store: import { STORES } from '@n8n/stores' ; export const useMyStore = defineStore ( STORES . MY_STORE , () => { const state = shallowRef ([]); return { state }; }); Vue Component: <script setup lang="ts"> type Props = { title: string }; const props = defineProps<Props>(); </script> Service: import { Service } from '@n8n/di' ; import { Config } from '@n8n/config' ; @Service () export class MyService { constructor ( private readonly config : Config ) {} } 📖 Need more details? Read /AGENTS.md and /packages/frontend/AGENTS.md