This quest issue tracks the implementation of Glimmer components in Ember.js.

The Plan

Glimmer.js components have the following features:

1. “Outer HTML” templates (no tagName, attributeBindings, etc.)
2. Arguments in templates are @ prefixed, like {{@firstName}}
3. Arguments are set on the component as this.args
4. Component classes use JavaScript class syntax
5. Mutable component state is annotated with @tracked properties
6. Components are invoked via <AngleBracket /> syntax
7. Attributes can be “splatted” via …attributes

In keeping with Ember’s spirit of incrementalism, we want to land this functionality piece by piece via an addon. This allows the community to start using features and providing feedback early in the process.

In fact, we’ve already started down the road to Glimmer components in Ember. The first two features have already started to land:

1. In template-only components, templates are “outer HTML” (assuming the template-only-glimmer-components optional feature has been enabled.)
2. Arguments can be accessed in the template via the @ prefix (e.g. {{@firstName}}).

This issue proposes finishing the process of bringing Glimmer components to Ember by allowing addons to provide alternate component implementations, then transforming the @glimmer/component package into an Ember addon that implements the Glimmer.js component API.

We’ll break that work into phases, each one unlocking benefits for existing Ember apps and addons. Phase 0 is about adding the necessary primitives to Ember.js to support alternate component implementations. Phases 1, 2 and 3 are about incrementally enabling Glimmer.js component API.

While we go into depth on Phases 0 and 1, we will defer exploring the technical details of later phases until the first phases are closer to completion.

Phase 0: Customizing Component Behavior

TL;DR: Add a CustomComponentManager API to Ember.js to allow addons to implement custom component API.

Currently, all components in an Ember app are assumed to be subclasses of Ember.Component. In order to support alternate component APIs in Ember, we need some way to tell Ember when and how component behavior should change.

When we say “custom component behavior,” we specifically mean:

1. How component instances are created.
2. How component instances are destroyed.
3. How arguments are provided to the component instance.
4. How the component is notified of these lifecycle changes.

While Glimmer VM introduces the concept of a “component manager,” an object that makes these decisions, this API is very low level. It would be premature to adopt them directly as public API in Ember because they are difficult to write, easy to author in a way that breaks other components, and not yet stable.

Instead, we propose a new Ember API called CustomComponentManager that implements a delegate pattern. The CustomComponentManager provides a smaller API surface area than the full-fledged ComponentManager Glimmer VM API, which allows addon authors to fall into a “pit of success.”

So how does Ember know which component manager to use for a given component? The original iteration of the Custom Components RFC introduced the concept of a ComponentDefinition, a data structure that was eagerly registered with Ember and specified which component manager to use.

One of the major benefits of the ComponentDefinition approach is that component manager resolution can happen at build time. Unfortunately, that means we have to design an API for exactly how these get registered, and likely means some sort of integration with the build pipeline.

Instead, we propose an API for setting a component’s manager at runtime via an annotation on the component class. This incremental step allows work on custom component managers to continue while a longer term solution is designed.

Custom Component Manager Discovery

In this iteration, components must explicitly opt-in to alternate component managers. They do this via a special componentManager function, exported by Ember, that annotates at runtime which component manager should be used for a particular component class:

import { componentManager } from '@ember/custom-component-manager';
import EmberObject from '@ember/object';

export default componentManager(EmberObject.extend({
  // ...
}), 'glimmer');

Eventually, this could become a class decorator:

import { componentManager } from '@ember/custom-component-manager';

export default @componentManager('glimmer') class {
  // ...
}

The first time this component is invoked, Ember inspects the class to see if it has a custom component manager annotation. If so, it uses the string value to perform a lookup on the container. In the example above, Ember would ask the container for the object with the container key component-manager:glimmer.

Addons can thus use normal resolution semantics to provide custom component managers. Our Glimmer component addon can export a component manager from addon/component-managers/glimmer.js that will get automatically discovered through normal resolution rules.

While this API is verbose and not particularly ergonomic, apps and addons can abstract it away by introducing their own base class with the annotation. For example, if an addon called turbo-component wanted to provide a custom component manager, it could export a base class like this:

// addon/index.js
import EmberObject from '@ember/object';
import { componentManager } from '@ember/custom-component-manager';

export default componentManager(EmberObject.extend({
  // ...
}), 'turbo');

Users of this addon could subclass the TurboComponent base class to define components that use the correct component manager:

import TurboComponent from 'turbo-component';

export default TurboComponent.extend({
  didInsertElementQuickly() {
    // ...
  }
});

Custom Component API

No component is an island, and for backwards compatibility reasons, it’s important that the introduction of new component API don’t break existing components.

One example of this is the existing view hierarchy API. Ember components can inspect their parent component via the parentView property. Even if the parent is not an Ember.Component, the child Ember components should still have a non-null parentView property.

Currently, the CurlyComponentManager in Ember is responsible for maintaining this state, as well as other ambient “scope state” like the target of actions.

To prevent poorly implemented component managers from violating invariants in the existing system, we use a compositional pattern to customize behavior while hiding the sharp corners of the underlying API.

import CustomComponentManager from "@ember/custom-component-manager";

export default new CustomComponentManager({
  // major and minor Ember version this manager targets
  version: "3.1",
  create({ ComponentClass, args }) {
    // Responsible for instantiating the component class and passing provided
    // component arguments.
    // The value returned here is passed as `component` in the below hooks.
  },
  getContext(component) {
    // Returns the object that serves as the root scope of the component template.
    // Most implementations should return `component`, so the component's properties
    // are looked up in curly expressions.
  },
  update(component, args) {
    // Called whenever the arguments to a component change.
  },
  destroy(component) {
  }
});

Phase 1: Ember Object Glimmer Components

The Component base class in Ember supports a long list of features, many of which are no longer heavily used. These features can impose a performance cost, even when they are unused.

As a first step, we want to provide a way to opt in to the simplified Glimmer.js component API via the @glimmer/component package. To ease migration, we will provide an implementation of the Glimmer Component base class that inherits from Ember.Object at @glimmer/component/compat.

Here’s an example of what an “Ember-Glimmer component” looks like:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from '@ember/object';

export default Component({
  fullName: computed('args.firstName', 'args.lastName', function() {
    let { firstName, lastName } = this.args
    return `${firstName} ${lastName}`;
  })

  isAdmin: false,

  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

{{!-- src/ui/components/user-profile/template.hbs --}}
<h1>{{fullName}}</h1>
<p>
  Welcome back, {{@firstName}}!
  {{#if isAdmin}}
    <strong>You are an admin.</strong>
  {{/if}}
</p>
<button {{action toggleAdmin}}>Toggle Admin Status</button>

Notable characteristics of these components:

• Templates are outer HTML. Because the example template above does not have a single root element, this renders as a “tagless component”.
• Actions are just functions on the component and don’t need to be nested in the actions hash.
• Arguments are set on the args property rather than setting individual properties on the component directly.
• They use the Ember object model. This means tools like computed properties and mixins that Ember developers are already familiar with continue to work.

Just as important is what is not included:

• @tracked properties will not be supported until Phase 3.
• No layout or template properties on the component.
• No methods or properties relating to the view hierarchy, such as childViews, parentView, nearestWithProperty, etc.
• No tagName, attributeBindings, or other custom JavaScript DSL for modifying the root element.
• No send or sendAction for dispatching events.
• No mandatory ember-view class or auto-generated guid element ID.
• No manual rerender() method.
• No attrs property (use args instead).
• Passed arguments are “unidirectional” and don’t create two-way bindings.
• Passed arguments are not set as properties on the component instance, avoiding the possibility of hard-to-debug naming collisions.
• No this.$() to create a jQuery object for the component element.
• No manual appendTo of components into the DOM.
• No support for the following lifecycle events:
  
  
  
  • willInsertElement
  
  
  • didRender
  
  
  • willRender
  
  
  • willClearRender
  
  
  • willUpdate
  
  
  • didReceiveAttrs
  
  
  • didUpdateAttrs
  
  
  • parentViewDidChange
  
  
• No on() event listener for component lifecycle events; hooks must be implemented as methods.

One interesting side effect of this set of features is that it dovetails with the effort to enable JavaScript classes. In conjunction with the design proposed in the ES Classes RFC, we can provide an alternate implementation of the above component:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from 'ember-decorators/object';

export default class extends Component {
  isAdmin = false;

  @computed('args.firstName', 'args.lastName')
  get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  })

  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

Phase 2 - Angle Bracket Syntax

Phase 2 enables invoking components via angle brackets (<UserAvatar @user={{currentUser}} />) in addition to curlies ({{my-component user=currentUser}}). Because this syntax disambiguates between component arguments and HTML attributes, this feature also enables “splatting” passed attributes into the component template via …attributes.

{{! src/ui/components/UserAvatar/template.hbs }}
<div ...attributes> {{! <-- attributes will be inserted here }}
  <h1>Hello, {{@firstName}}!</h1>
</div>

<UserAvatar @user={{currentUser}} aria-expanded={{isExpanded}} />

This would render output similar to the following:

<div aria-expanded="true">
  <h1>Hello, Steven!</h1>
</div>

Phase 3 - Tracked Properties

Phase 3 enables tracked properties via the @tracked decorator in Ember. The details of the interop between Ember’s object model and tracked properties is being worked out. Once tracked properties land, users will be able to drop the @glimmer/component/compat module and use the normal, non-Ember.Object component base class.

In tandem with the recently-merged “autotrack” feature (which infers computed property dependencies automatically), this should result in further simplification of application code:

import Component, { tracked } from '@glimmer/component';

export default class extends Component {
  @tracked isAdmin = false;

  @tracked get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  }

  toggleAdmin() {
    this.isAdmin = !this.isAdmin;
  }
}

Q&A

Can I add back things like the ember-view class name or auto-generated id attribute to Glimmer components for compatibility with existing CSS?

Yes. Example:

<div class="ember-view" id="{{uniqueId}}">
  Component content goes here.
</div>

import Component from '@glimmer/component';
import { guidFor } from '@ember/object/internals';

export default class extends Component {
  get uniqueId() {
    return guidFor(this);
  }
}

Resources

• #st-glimmer-components channel on the Ember community Slack
  
  
  
  • We're coordinating the work here.
  
  
• Custom Component RFC
• custom-component-manager branch
  
  
  
  • In-progress branch of Ember.js with CustomComponentManager implementation behind a feature flag
  
  
• tracked branch
  
  
  
  • In-progress branch of Ember.js with work on interop between @tracked properties and Ember objects
  
  

Tasks

We’ll use the lists below to track ongoing work. As we learn more during implementation, we will add or remove items on the list.

Custom Component Manager API

• [x] Update Custom Component RFC to reflect changes above (@chancancode)
  
  
  
  • https://github.com/emberjs/rfcs/pull/213#issuecomment-370494713
  
  
• [x] Add glimmer-custom-component-manager feature flag
• [x] Implement componentManager function
  
  
  
  • [x] Expose as { componentManager } from '@ember/custom-component-manager'
  
  
• [x] Resolver needs to detect annotated classes
• [x] Resolver needs to look up specified component manager
  
  
  
  • [ ] Guidance for addon authors about where to put component managers so they are discovered
  
  
  • [ ] How does this work with Module Unification? (@mixonic)
  
  
• [x] Implement CustomComponentManager API
  
  
  
  • [x] Define the CustomComponentManagerDelegate interface
  
  
  • [x] version
  
  
  • [x] create()
  
  
  • [x] getContext()
  
  
  • [x] update()
  
  
  • [x] destroy?()
  
  
  • [x] didCreate?()
  
  
  • [x] didUpdate?()
  
  
  • [x] getView?()
  
  
  • [x] Validate version property upon creation
  
  
  • [x] Internals
  
  
  • [x] Preserve childViews and parentView in existing components
  
  
  • [ ] Instrument for rendering performance
  
  
  • [ ] Instrument for compatibility with Ember Inspector
  
  

Glimmer Component Addon

• [x] Support using sparkles-components addon
  
  
  
  • [x] Base class should import and add componentManager annotation when consumed from Ember
  
  
  • [x] CustomComponentManager implementation should be discoverable via Ember’s container
  
  
• [ ] Support using @glimmer/component as an Ember addon
  
  
  
  • [ ] Preserve existing behavior when consumed from Glimmer.js
  
  
  • [ ] import Component from '@glimmer/component' provides plain JavaScript base class
  
  
  • [ ] import Component from '@glimmer/component/compat' provides Ember.Object base class
    
    lookup
  
  
• [ ] Lifecycle Hooks
  
  
  
  • [x] static create(injections)
  
  
  • [x] didInsertElement()
  
  
  • [x] willDestroy()
  
  
  • [x] didUpdate()
  
  
  • [x] Event delegation-invoked methods (click() etc.) should not be triggered
  
  
• [ ] Element Access
  
  
  
  • [ ] this.bounds
  
  
  • [ ] this.element computed property alias to this.bounds
  
  
  • [ ] Element modifier-based API for exposing elements
  
  
• [ ] Arguments
  
  
  
  • [x] this.args is available in the constructor
  
  
  • [x] this.args is updated before didUpdate is called
  
  
  • [ ] this.args should not trigger an infinite re-render cycle (need to verify)
  
  
• [ ] Documentation
  
  
  
  • [ ] How to install
  
  
  • [ ] Caveats
  
  
  • [ ] Canary-only
  
  
  • [ ] Pre-1.0
  
  
  • [ ] Ember-Glimmer “compat” components
  
  
  • [ ] Outer HTML templates
  
  
  • [ ] Lifecycle hooks
  
  
  • [ ] Defining computed properties
    
    
    
    
    
    • [ ] How to depend on args
    
    
    
  
  
  • [ ] Migration Guide / Glimmer Components for…
  
  
  • Guides for writing effective Glimmer components for people familiar with other libraries
  
  
  • [ ] Glimmer Components for Ember Developers
  
  
  • [ ] Glimmer Components for React Developers
  
  
  • [ ] Glimmer Components for Angular Developers
  
  
  • [ ] Glimmer Components for COBOL Developers
  
  

Open Questions

1. What are the best practices for actions? Is this something we need to allow component managers to hook into?
2. How do you use bare JavaScript classes (those with no static create() method) as component classes? The protocol for initializing a component seems simple but is surprisingly tricky.
3. Where is the best place to document “addon APIs” like CustomComponentManager?
4. How do we handle CustomComponentManager versioning?