Ember.js Framework Core

Common errors

• Cannot find module '@glimmer/component' or its corresponding type declarations.

  cause Ember applications or addons using Glimmer components might miss the `@glimmer/component` dependency, or the build system isn't correctly configured to resolve it after the monorepo merge.
  fix Ensure `@glimmer/component` is listed in your `package.json` peerDependencies (for addons) or dependencies (for apps) and that `ember-source` is at a compatible version. If on v6.12.0+, verify your Ember CLI version is recent enough to handle the internal Glimmer VM changes.

• TypeError: GlimmerComponent is not a constructor

  cause This error likely occurs after upgrading to Ember v6.11.0 or later, where the default export `GlimmerComponent` from `@glimmer/component` was renamed.
  fix Change your import statement from `import GlimmerComponent from '@glimmer/component';` to `import Component from '@glimmer/component';`.

• Error: Assertion Failed: You must use 'tracked' to mark properties that you intend to use in a template or update reactively.

  cause A property used in a template or relied upon for reactivity was modified, but not decorated with `@tracked`.
  fix Add the `@tracked` decorator from `@glimmer/tracking` to any component property whose changes should trigger a re-render or be reactive.

Warnings

• breaking As of v6.12.0, the Glimmer VM and all `@glimmer/*` packages are merged directly into the `emberjs/ember.js` monorepo. This primarily affects core contributors and integrators, simplifying internal iteration, but might subtly change dependency resolution or tree-shaking behavior in specific edge cases for advanced build setups.
  Fix: For most applications, no direct change is required. Ensure your Ember CLI and related tooling are up-to-date to correctly handle the new monorepo structure. If you had explicit `@glimmer/*` dependencies, they might no longer be needed or should be removed.
• breaking The default export `GlimmerComponent` from `@glimmer/component` was renamed to `Component` to improve developer experience and autocomplete. Code directly importing `GlimmerComponent` will break.
  Fix: Update your imports from `import GlimmerComponent from '@glimmer/component';` to `import Component from '@glimmer/component';`.
• gotcha Ember's module resolution typically requires using `import` statements at the top level, even though `ember-source` itself ships CommonJS bundles for Node.js environments (like FastBoot). Direct `require()` calls for framework internals are generally discouraged in application code.
  Fix: Always use ES module `import` syntax (`import { Thing } from 'module';`) in your Ember application and addon code. Ember CLI will transpile this correctly for your target environments.
• gotcha Using `ApplicationInstance#visit` might throw a `TransitionAborted` error if not handled correctly, especially in FastBoot or during rapid navigation/redirects.
  Fix: Update Ember to at least v6.11.1 or v6.8.4 (for older stable lines) which includes a bugfix to use `followRedirects()` internally. When using `visit()` directly, be prepared to catch and handle `TransitionAborted` errors gracefully.
• gotcha FastBoot environments experienced crashes during component/application destruction, particularly with complex component hierarchies.
  Fix: Ensure your `ember-source` version is at least v6.11.1 or v6.8.4 to benefit from bug fixes addressing crashes during destroy in FastBoot.

Install

• npm install ember-source npm
• yarn add ember-source yarn
• pnpm add ember-source pnpm

Imports

• Component
  wrong:

  import { Component } from '@ember/component';

  correct:

  import Component from '@glimmer/component';

  While older Ember versions might have used `@ember/component`, the modern way for Glimmer components is via `@glimmer/component`. Note: in v6.11.0, the default export `GlimmerComponent` was renamed to `Component` for better DX.
• tracked
  wrong:

  import { tracked } from '@ember/object';

  correct:

  import { tracked } from '@glimmer/tracking';

  Properties that trigger re-renders in Glimmer components are marked with `tracked`. This is a core reactive primitive.
• action
  wrong:

  import { action } from '@ember/component';

  correct:

  import { action } from '@ember/object';

  The `@action` decorator is used to bind methods to the component instance and ensure they are properly handled by Ember's event system.

Quickstart

This quickstart demonstrates a basic Glimmer component with `tracked` properties and an `@action` decorator.

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

interface Args {
  message: string;
}

export default class GreetingComponent extends Component<Args> {
  @tracked count = 0;

  get greeting() {
    return `${this.args.message} World! You clicked ${this.count} times.`;
  }

  @action
  increment() {
    this.count++;
  }

  // Example of a lifecycle hook
  constructor(owner: unknown, args: Args) {
    super(owner, args);
    console.log('GreetingComponent initialized with message:', this.args.message);
  }
}