Ember.js Best Practices
Comprehensive performance optimization and accessibility guide for Ember.js applications. Contains 58 rules across 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 loadingroute-loading-substates- Implement loading substates for better UXroute-lazy-routes- Use route-based code splitting with Embroiderroute-templates- Use route templates with co-located syntaxroute-model-caching- Implement smart route model caching
2. Build and Bundle Optimization (CRITICAL)
bundle-direct-imports- Import directly, avoid entire namespacesbundle-embroider-static- Enable Embroider static mode for tree-shakingbundle-lazy-dependencies- Lazy load heavy dependencies
3. Component and Reactivity Optimization (HIGH)
component-use-glimmer- Use Glimmer components over classic componentscomponent-cached-getters- Use @cached for expensive computationscomponent-minimal-tracking- Only track properties that affect renderingcomponent-tracked-toolbox- Use tracked-built-ins for complex statecomponent-composition-patterns- Use yield blocks and contextual componentscomponent-reactive-chains- Build reactive chains with dependent getterscomponent-class-fields- Use class fields for component compositioncomponent-controlled-forms- Implement controlled form patternscomponent-on-modifier- Use {{on}} modifier for event handlingcomponent-args-validation- Validate component argumentscomponent-memory-leaks- Prevent memory leaks in componentscomponent-strict-mode- Use strict mode and template-only componentscomponent-avoid-classes-in-examples- Avoid unnecessary classes in component examplescomponent-avoid-constructors- Avoid constructors in Glimmer componentscomponent-avoid-lifecycle-hooks- Avoid legacy lifecycle hookscomponent-file-conventions- Follow proper file naming conventionsexports-named-only- Use named exports only
4. Accessibility Best Practices (HIGH)
a11y-automated-testing- Use ember-a11y-testing for automated checksa11y-semantic-html- Use semantic HTML and proper ARIA attributesa11y-keyboard-navigation- Ensure full keyboard navigation supporta11y-form-labels- Associate labels with inputs, announce errorsa11y-route-announcements- Announce route transitions to screen readers
5. Service and State Management (MEDIUM-HIGH)
service-cache-responses- Cache API responses in servicesservice-shared-state- Use services for shared stateservice-ember-data-optimization- Optimize WarpDrive queriesservice-owner-linkage- Manage service owner and linkage patternsservice-data-requesting- Implement robust data requesting patterns
6. Template Optimization (MEDIUM)
template-let-helper- Use {{#let}} to avoid recomputationtemplate-each-key- Use {{#each}} with @key for efficient list updatestemplate-avoid-computation- Move expensive work to cached getterstemplate-helper-imports- Import helpers directly in templatestemplate-conditional-rendering- Optimize conditional renderingtemplate-fn-helper- Use {{fn}} helper for partial applicationtemplate-only-component-functions- Use template-only componentshelper-composition- Compose helpers for reusable logichelper-builtin-functions- Use built-in helpers effectivelyhelper-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 patternstesting-qunit-dom-assertions- Use qunit-dom for better test assertionstesting-test-waiters- Use @ember/test-waiters for async testingtesting-render-patterns- Use correct render patterns for componentstesting-msw-setup- Mock API requests with MSWtesting-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 effectsadvanced-helpers- Extract reusable logic into helpersadvanced-tracked-built-ins- Use reactive collections from @ember/reactive/collectionsadvanced-concurrency- Use ember-concurrency for task managementadvanced-data-loading-with-ember-concurrency- Data loading patterns with ember-concurrency
How to Use
Read individual rule files for detailed explanations and code examples:
rules/route-parallel-model.md
rules/bundle-embroider-static.md
rules/a11y-automated-testing.mdEach rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Accessibility with OSS Tools
Ember has excellent accessibility support through community addons:
- ember-a11y-testing - Automated accessibility testing in your test suite
- ember-a11y - 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