n8n-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Quick Reference

n8n 快速参考

📚 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.

📚 完整文档：

通用部分：
```
/AGENTS.md
```
- 架构、命令、工作流
前端部分：
```
/packages/frontend/AGENTS.md
```
- CSS变量、计时规则

当你需要快速查阅关键开发模式时，可以使用这份参考资料。

Critical Rules (Must Follow)

核心规则（必须遵守）

TypeScript:

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

Error Handling:

typescript

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

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

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

TypeScript：

禁止使用
```
any
```
类型 → 改用
```
unknown
```
优先使用
```
satisfies
```
而非
```
as
```
（测试场景除外）
共享类型定义在
```
@n8n/api-types
```
中

错误处理：

typescript

import { UnexpectedError } from 'n8n-workflow';
throw new UnexpectedError('message', { extra: { context } });
// 禁止使用已废弃的ApplicationError

前端：

使用Vue 3组合式API（
```
<script setup lang="ts">
```
）
使用CSS变量（禁止硬写px值）- 详情请查看
```
/packages/frontend/AGENTS.md
```
所有文本通过i18n处理（
```
$t('key')
```
）
E2E测试使用
```
data-testid
```
（单一值，无空格）

后端：

遵循Controller → Service → Repository架构
通过
```
@n8n/di
```
实现依赖注入
通过
```
@n8n/config
```
管理配置
使用Zod schema进行校验

测试：

单元测试使用Vitest，E2E测试使用Playwright
对外部依赖进行Mock
在包目录下执行测试：
```
pushd packages/cli && pnpm test
```

数据库：

应用数据库仅支持SQLite/PostgreSQL
例外：数据库节点（如MySQL节点）可使用数据库特定功能

命令：

bash

pnpm build > build.log 2>&1  # 始终重定向输出
pnpm typecheck               # 提交前执行类型检查
pnpm lint                    # 提交前执行代码检查

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

包	用途
`packages/cli`	后端API
`packages/frontend/editor-ui`	Vue 3前端
`packages/@n8n/api-types`	共享类型定义
`packages/@n8n/db`	TypeORM实体
`packages/workflow`	核心接口

Common Patterns

常见模式

Pinia Store:

typescript

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

Vue Component:

vue

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

Service:

typescript

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

Pinia Store：

typescript

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

Vue组件：

vue

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

服务类：

typescript

import { Service } from '@n8n/di';
import { Config } from '@n8n/config';

@Service()
export class MyService {
  constructor(private readonly config: Config) {}
}

📖 需要更多细节？ 请阅读

/AGENTS.md

和

/packages/frontend/AGENTS.md