ember-best-practices

Ember.js Best Practices

Comprehensive performance optimization and accessibility guide for Ember.js applications. Its rules span 10 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Ember components or routes
• Implementing data fetching with WarpDrive
• Reviewing code for performance issues
• Refactoring existing Ember.js code
• Optimizing bundle size or load times
• Implementing accessibility features

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Route Loading and Data Fetching	CRITICAL	route-
2	Build and Bundle Optimization	CRITICAL	bundle-
3	Component and Reactivity	HIGH	component-, exports-
4	Accessibility Best Practices	HIGH	a11y-
5	Service and State Management	MEDIUM-HIGH	service-
6	Template Optimization	MEDIUM	template-, helper-
7	Performance Optimization	MEDIUM	performance-
8	Testing Best Practices	MEDIUM	testing-
9	Tooling and Configuration	MEDIUM	vscode-
10	Advanced Patterns	MEDIUM-HIGH	advanced-

Quick Reference

1. Route Loading and Data Fetching (CRITICAL)

• route-parallel-model - Use RSVP.hash() for parallel data loading
• route-loading-substates - Implement loading substates for better UX
• route-lazy-routes - Use route-based code splitting with Embroider
• route-templates - Use route templates with co-located syntax
• route-model-caching - Implement smart route model caching

2. Build and Bundle Optimization (CRITICAL)

• bundle-direct-imports - Import directly, avoid entire namespaces
• bundle-embroider-static - Enable Embroider static mode for tree-shaking
• bundle-lazy-dependencies - Lazy load heavy dependencies

3. Component and Reactivity Optimization (HIGH)

• component-use-glimmer - Use Glimmer components over classic components
• component-cached-getters - Use @cached for expensive computations
• component-minimal-tracking - Only track properties that affect rendering
• component-no-tracked-writes-in-render - Don't update tracked state while rendering
• component-tracked-toolbox - Use tracked collections for complex state
• component-composition-patterns - Use yield blocks and contextual components
• component-reactive-chains - Build reactive chains with dependent getters
• component-class-fields - Use class fields for component composition
• component-standalone-tracked - Keep app state on classes, not in standalone tracked() values
• component-controlled-forms - Implement controlled form patterns
• component-on-modifier - Use {{on}} modifier for event handling
• component-args-validation - Validate component arguments
• component-signatures - Write precise signatures for components, helpers and modifiers
• component-memory-leaks - Prevent memory leaks in components
• component-strict-mode - Use strict mode and template-only components
• component-avoid-classes-in-examples - Avoid unnecessary classes in component examples
• component-avoid-constructors - Avoid constructors in Glimmer components
• component-avoid-lifecycle-hooks - Avoid legacy lifecycle hooks
• component-file-conventions - Follow proper file naming conventions
• exports-named-with-default-fallback - Prefer named exports, with a default export for template lookup

4. Accessibility Best Practices (HIGH)

• a11y-automated-testing - Use ember-a11y-testing for automated checks
• a11y-semantic-html - Use semantic HTML and proper ARIA attributes
• a11y-keyboard-navigation - Ensure full keyboard navigation support
• a11y-form-labels - Associate labels with inputs, announce errors
• a11y-route-announcements - Announce route transitions to screen readers

5. Service and State Management (MEDIUM-HIGH)

• service-cache-responses - Cache API responses in services
• service-shared-state - Use services for shared state
• service-ember-data-optimization - Optimize WarpDrive queries
• service-owner-linkage - Manage service owner and linkage patterns
• service-data-requesting - Implement robust data requesting patterns

6. Template Optimization (MEDIUM)

• template-let-helper - Use {{#let}} to avoid recomputation
• template-each-key - Use {{#each}} with @key for efficient list updates
• template-avoid-computation - Move expensive work to cached getters
• template-helper-imports - Import helpers directly in templates
• template-conditional-rendering - Optimize conditional rendering
• template-fn-helper - Use {{fn}} helper for partial application
• template-only-component-functions - Use template-only components
• helper-composition - Compose helpers for reusable logic
• helper-builtin-functions - Use built-in helpers effectively
• helper-plain-functions - Write helpers as plain functions

7. Performance Optimization (MEDIUM)

• performance-on-modifier-vs-handlers - Use {{on}} modifier instead of event handler properties

8. Testing Best Practices (MEDIUM)

• testing-modern-patterns - Use modern testing patterns
• testing-qunit-dom-assertions - Use qunit-dom for better test assertions
• testing-test-waiters - Use @ember/test-waiters for async testing
• testing-render-patterns - Use correct render patterns for components
• testing-msw-setup - Mock API requests with MSW
• testing-library-dom-abstraction - Use Testing Library patterns

9. Tooling and Configuration (MEDIUM)

• vscode-setup-recommended - VS Code extensions and MCP server setup

10. Advanced Patterns (MEDIUM-HIGH)

• advanced-modifiers - Use modifiers for DOM side effects
• advanced-modifier-reruns - Keep expensive modifier setup separate from updates
• advanced-helpers - Extract reusable logic into helpers
• advanced-tracked-built-ins - Use reactive collections from @ember/reactive/collections
• advanced-concurrency - Use ember-concurrency for task management
• advanced-data-loading-with-ember-concurrency - Data loading patterns with ember-concurrency

How to Use

Each entry in the Quick Reference links to its rule in references/. Read the rules that apply to the task before writing or reviewing code, rather than loading them all.

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Links to the official documentation it is based on

Accessibility with OSS Tools

Ember has excellent accessibility support through community addons:

• ember-a11y-testing - Automated accessibility testing in your test suite
• ember-a11y-refocus - Route announcements and focus management
• ember-focus-trap - Focus trapping for modals and dialogs
• ember-page-title - Accessible page title management
• Platform-native validation - Use browser's Constraint Validation API for accessible form validation

These tools, combined with native web platform features, provide comprehensive a11y support with minimal configuration.

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md