Index of every page on this site: llms.txt
All skills
n8n-io avatar

/conventions

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

Quick reference for n8n patterns. Full docs /AGENTS.md

  • 1 file
  • 3.3 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/n8n-io/n8n/conventions

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈17 tokens for metadata: the name and description. ≈814 when used: this file.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈72 characters, or 0.9%.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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/errors';
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
  • 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:

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 shell
packages/modules/<name>/frontend Frontend feature modules. Guide: packages/@n8n/module-cli/frontend-module-guide.md
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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
  • TypeScript
  • n8n
  • vue3
  • vitest
  • playwright
  • error-handling
  • dependency-injection
  • zod
  • pinia
  • typeorm

README badge

README badge for n8n-io/n8n/conventions

Consolidates n8n coding conventions for TypeScript, Vue 3 frontend, backend services, testing, and database patterns. References the full `/AGENTS.md` documentation for architecture details and frontend CSS variable standards. Use this skill when you need quick reminders on critical patterns like error handling, dependency injection, Zod validation, and Vitest/Playwright test setup.

Generated from the current SKILL.md.

Should I use `any` type in TypeScript code?
No. Use `unknown` instead. Prefer `satisfies` over `as` for type assertions, except in tests.
What error class should I throw in n8n code?
Import and throw `UnexpectedError` from `n8n-workflow` with optional context. Do not use the deprecated `ApplicationError`.
What frontend framework and patterns does n8n use?
Vue 3 with Composition API and `<script setup lang="ts">`. All text must use i18n (`$t('key')`), CSS must use variables (no hardcoded px), and interactive elements need `data-testid` attributes.
What testing frameworks does n8n use?
Vitest for unit tests and Playwright for E2E tests. Run tests from the package directory (e.g., `pushd packages/cli && pnpm test`).
What databases does the n8n app support?
SQLite and PostgreSQL only for the application database. Database-specific nodes (MySQL Node, etc.) can use their own DB features.

Generated from the current SKILL.md. These answers refresh after source changes.