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)

TypeScript:

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

Error Handling:

typescript
1import { UnexpectedError } from 'n8n-workflow';
2throw new UnexpectedError('message', { extra: { context } });
3// 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

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

Commands:

bash
1pnpm build > build.log 2>&1  # Always redirect
2pnpm typecheck               # Before commit
3pnpm lint                    # Before commit

Key Packages

Common Patterns

Pinia Store:

typescript
1import { STORES } from '@n8n/stores';
2export const useMyStore = defineStore(STORES.MY_STORE, () => {
3  const state = shallowRef([]);
4  return { state };
5});

Vue Component:

vue
1<script setup lang="ts">
2type Props = { title: string };
3const props = defineProps<Props>();
4</script>

Service:

typescript
1import { Service } from '@n8n/di';
2import { Config } from '@n8n/config';
3
4@Service()
5export class MyService {
6  constructor(private readonly config: Config) {}
7}

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