n8n-conventions

n8n クイックリファレンス

📚 詳細なドキュメント：

• 全般： /AGENTS.md - アーキテクチャ、コマンド、ワークフロー
• フロントエンド： /packages/frontend/AGENTS.md - CSS 変数、タイミング

重要なパターンをすばやく確認したい場合は、このスキルを使用してください。

重要なルール（必ず従ってください）

TypeScript：

• any は使わず、unknown を使用してください
• （テストを除き）as より satisfies を優先してください
• 共通の型は @n8n/api-types に定義してください

エラー処理：

import { UnexpectedError } from 'n8n-workflow';
throw new UnexpectedError('message', { extra: { context } });
// DON'T use deprecated ApplicationError

フロントエンド：

• Vue 3 Composition API（<script setup lang="ts">）
• CSS 変数を使用してください（px を直接指定しないでください）。/packages/frontend/AGENTS.md を参照してください
• すべてのテキストに i18n（$t('key')）を使用してください
• E2E には data-testid を使用してください（値は 1 つのみ。スペースは使用しないでください）

バックエンド：

• Controller → Service → Repository
• @n8n/di による依存性注入
• @n8n/config による設定
• バリデーションには Zod スキーマを使用してください

テスト：

• Vitest（ユニットテスト）、Playwright（E2E）
• 外部依存関係をモックしてください
• パッケージのディレクトリから実行してください：pushd packages/cli && pnpm test

データベース：

• SQLite/PostgreSQL のみ（アプリ DB）
• 例外：DB ノード（MySQL Node など）では、データベース固有の機能を使用できます

コマンド：

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

主要なパッケージ

パッケージ	用途
packages/cli	バックエンド API
packages/frontend/editor-ui	Vue 3 フロントエンド
packages/@n8n/api-types	共通の型
packages/@n8n/db	TypeORM エンティティ
packages/workflow	コアインターフェース

よくあるパターン

Pinia ストア：

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

Vue コンポーネント：

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

サービス：

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 をお読みください