n8n:conventions

n8n クイックリファレンス

📚 ドキュメント全文：

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

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

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

技術文書（コメント、PR、Issue、ドキュメント）：

• ASD-STE100 の平易な技術英語で記述してください。短い文を使い、能動態にし、1文につき1つの指示を記述してください。

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 スキーマを使用してください。
• ページネーション引数：Controller と Service では offset と limit を使用してください。TypeORM の skip／take への変換は Repository 内でのみ行ってください。

テスト：

• Vitest（ユニットテスト）、Playwright（E2E）
• 外部依存関係をモックしてください。
• ファイルシステムのテストは、テスト専用の一時ディレクトリ内で実施してください。
• 設定コードをインポートする前に N8N_USER_FOLDER を設定してください。
• モックで有効になる分岐を追跡し、到達可能な各ミューテーションを個別に分離してください。
• パッケージディレクトリで作業してください：pushd packages/cli && pnpm test

データベース：

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

GitHub ワークフロー：

• すべてのワークフローで、最小権限のトップレベル permissions: ブロックを宣言してください （通常は contents: read）。より多くの権限が必要なジョブでは、ジョブレベルで上書きしてください。

コマンド：

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

シークレット：オプトイン方式の開発メトリクスにより、pnpm のコマンドラインがそのまま記録される場合があります。 機密情報は環境変数で渡し、コマンドラインに直接記述しないでください。

主なパッケージ

パッケージ	用途
packages/cli	バックエンド API
packages/frontend/editor-ui	Vue 3 フロントエンドシェル
packages/modules/<name>/frontend	フロントエンド機能モジュール。ガイド：packages/@n8n/module-cli/frontend-module-guide.md
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 をお読みください