ember-best-practices

Ember.js のベストプラクティス

Ember.js アプリケーション向けの包括的なパフォーマンス最適化とアクセシビリティのガイドです。ルールは10のカテゴリに分かれており、影響度の高い順に並べて、自動リファクタリングとコード生成を支援します。

適用するタイミング

次の作業を行う際に、これらのガイドラインを参照してください。

• 新しい Ember コンポーネントやルートを作成するとき
• WarpDrive を使用してデータ取得を実装するとき
• パフォーマンスの問題がないかコードをレビューするとき
• 既存の Ember.js コードをリファクタリングするとき
• バンドルサイズや読み込み時間を最適化するとき
• アクセシビリティ機能を実装するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	ルートの読み込みとデータ取得	CRITICAL	route-
2	ビルドとバンドルの最適化	CRITICAL	bundle-
3	コンポーネントとリアクティビティ	HIGH	component-, exports-
4	アクセシビリティのベストプラクティス	HIGH	a11y-
5	サービスと状態管理	MEDIUM-HIGH	service-
6	テンプレートの最適化	MEDIUM	template-, helper-
7	パフォーマンスの最適化	MEDIUM	performance-
8	テストのベストプラクティス	MEDIUM	testing-
9	ツールと設定	MEDIUM	vscode-
10	高度なパターン	MEDIUM-HIGH	advanced-

クイックリファレンス

1. ルートの読み込みとデータ取得（CRITICAL）

• route-parallel-model - 並列データ読み込みには RSVP.hash() を使用します
• route-loading-substates - UX を向上させるため、読み込み中のサブステートを実装します
• route-lazy-routes - Embroider でルートベースのコード分割を使用します
• route-templates - 同一ディレクトリ構文を使用したルートテンプレートを使用します
• route-model-caching - スマートなルートモデルキャッシュを実装します

2. ビルドとバンドルの最適化（CRITICAL）

• bundle-direct-imports - 直接インポートし、名前空間全体のインポートは避けます
• bundle-embroider-static - ツリーシェイキングのために Embroider の静的モードを有効にします
• bundle-lazy-dependencies - サイズの大きい依存関係を遅延読み込みします

3. コンポーネントとリアクティビティの最適化（HIGH）

• component-use-glimmer - クラシックコンポーネントより Glimmer コンポーネントを使用します
• component-cached-getters - 計算コストの高い処理には @cached を使用します
• component-minimal-tracking - レンダリングに影響するプロパティのみを追跡します
• component-no-tracked-writes-in-render - レンダリング中に追跡対象の状態を更新しないでください
• component-tracked-toolbox - 複雑な状態には追跡可能なコレクションを使用します
• component-composition-patterns - yield ブロックとコンテキストコンポーネントを使用します
• component-reactive-chains - 依存するゲッターでリアクティブなチェーンを構築します
• component-class-fields - コンポーネントの合成にはクラスフィールドを使用します
• component-standalone-tracked - アプリの状態は standalone tracked() 値ではなく、クラスで管理します
• component-controlled-forms - 制御されたフォームのパターンを実装します
• component-on-modifier - イベント処理には {{on}} 修飾子を使用します
• component-args-validation - コンポーネントの引数を検証します
• component-signatures - コンポーネント、ヘルパー、修飾子のシグネチャを正確に記述します
• component-memory-leaks - コンポーネントのメモリーリークを防ぎます
• component-strict-mode - strict mode とテンプレート専用コンポーネントを使用します
• component-avoid-classes-in-examples - コンポーネントの例で不要なクラスを避けます
• component-avoid-constructors - Glimmer コンポーネントでコンストラクターを避けます
• component-avoid-lifecycle-hooks - レガシーなライフサイクルフックを避けます
• component-file-conventions - 適切なファイル命名規則に従います
• exports-named-with-default-fallback - 名前付きエクスポートを優先し、テンプレート検索用にデフォルトエクスポートを用意します

4. アクセシビリティのベストプラクティス（HIGH）

• a11y-automated-testing - 自動チェックには ember-a11y-testing を使用します
• a11y-semantic-html - セマンティック HTML と適切な ARIA 属性を使用します
• a11y-keyboard-navigation - キーボードだけで完全に操作できるようにします
• a11y-form-labels - ラベルを入力欄に関連付け、エラーを読み上げます
• a11y-route-announcements - スクリーンリーダーにルートの遷移を通知します

5. サービスと状態管理（MEDIUM-HIGH）

• service-cache-responses - サービスで API レスポンスをキャッシュします
• service-shared-state - 共有状態にはサービスを使用します
• service-ember-data-optimization - WarpDrive クエリーを最適化します
• service-owner-linkage - サービスの owner と linkage のパターンを管理します
• service-data-requesting - 堅牢なデータリクエストのパターンを実装します

6. テンプレートの最適化（中）

• template-let-helper - {{#let}}を使って再計算を避けます
• template-each-key - @keyを指定した{{#each}}を使って、リストの更新を効率化します
• template-avoid-computation - コストの高い処理をキャッシュ済みゲッターに移します
• template-helper-imports - ヘルパーをテンプレートに直接インポートします
• template-conditional-rendering - 条件付きレンダリングを最適化します
• template-fn-helper - 部分適用には{{fn}}ヘルパーを使います
• template-only-component-functions - テンプレートのみのコンポーネントを使います
• helper-composition - ヘルパーを組み合わせて、再利用可能なロジックを作成します
• helper-builtin-functions - 組み込みヘルパーを効果的に使います
• helper-plain-functions - ヘルパーを通常の関数として記述します

7. パフォーマンスの最適化（中）

• performance-on-modifier-vs-handlers - イベントハンドラープロパティの代わりに{{on}}モディファイアを使います

8. テストのベストプラクティス（中）

• testing-modern-patterns - 最新のテストパターンを使います
• testing-qunit-dom-assertions - より適切なテストアサーションにはqunit-domを使います
• testing-test-waiters - 非同期テストには@ember/test-waitersを使います
• testing-render-patterns - コンポーネントには適切なレンダリングパターンを使います
• testing-msw-setup - MSWでAPIリクエストをモックします
• testing-library-dom-abstraction - Testing Libraryのパターンを使います

9. ツールと設定（中）

• vscode-setup-recommended - VS Code拡張機能とMCP サーバーの設定

10. 高度なパターン（中～高）

• advanced-modifiers - DOMの副作用にはモディファイアを使います
• advanced-modifier-reruns - コストの高いモディファイアのセットアップを更新処理から分離します
• advanced-helpers - 再利用可能なロジックをヘルパーに切り出します
• advanced-tracked-built-ins - @ember/reactive/collectionsのリアクティブなコレクションを使います
• advanced-concurrency - タスク管理にはember-concurrencyを使います
• advanced-data-loading-with-ember-concurrency - ember-concurrencyを使ったデータ読み込みパターン

使用方法

クイックリファレンスの各項目から、references/にある該当ルールへ移動できます。すべてのルールを読み込むのではなく、コードの作成またはレビューを始める前に、作業に適用されるルールを読んでください。

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 参照元となる公式ドキュメントへのリンク

OSSツールによるアクセシビリティ

Emberは、コミュニティアドオンによる優れたアクセシビリティサポートを備えています。

• ember-a11y-testing - テストスイートでアクセシビリティを自動テストします
• ember-a11y-refocus - ルート変更の通知とフォーカス管理を行います
• ember-focus-trap - モーダルやダイアログでフォーカスをトラップします
• ember-page-title - アクセシブルなページタイトルを管理します
• プラットフォーム標準の検証 - ブラウザーのConstraint Validation APIを使って、アクセシブルなフォーム検証を行います

これらのツールをWebプラットフォームのネイティブ機能と組み合わせることで、最小限の設定で包括的なa11yサポートを提供できます。

コンパイル済みのドキュメント全体

すべてのルールを含む完全なガイドについては、AGENTS.mdを参照してください。