Ember 3.1 Release Blog Post

[locks]

• Rendered
• Preview

Sign-offs

• Ember.js (@chancancode)
• Ember Data (@bmac)
• Ember CLI (@rwjblue)
• Website (@locks, @mixonic)

Checklist

• Ember
  • Blog
  • v3.1.0
  • v3.2.0-beta.1
• Ember Data
  • Blog
  • v3.1.0
  • v3.2.0-beta.1
• Ember CLI
  • Blog
  • v3.1.0
  • v3.2.0-beta.1

See https://github.com/emberjs/website/pull/2824/files for inspiration.

[Turbo87]

• #7601 blueprints/addon: Replace test with test:all @Turbo87

test will run ember test now (like in apps), test:all will use ember-try to run tests in all configured scenarios

• #7492 Use yarn instead of npm when part of a yarn workspace root @thetimothyp

yarn.lock file detection improved

• #7573 Install optional dependencies when creating a new project @t-sauer

Fixes issues with the Glimmer blueprints

• #7586 add feature flag to project.isModuleUnification @GavinJoyce
• #7541 Add project.isModuleUnification() @GavinJoyce

Module Unification continues...

[Turbo87]

no new deprecations

[Turbo87]

• #7605 blueprints/app: Add qunit-dom dependency by default @Turbo87

qunit-dom will be added by default to all apps and addons, if you don't (plan to) use it you don't have to add it.
https://github.com/simplabs/qunit-dom-codemod exists to ease migration.

• #7501 add delayed transpilation @kellyselden
• #7650 compile all addons at once optimization @kellyselden

experiments with more efficient transpilation

• #7637 More comprehensive detect if ember-cli is being run within CI or not. @ember-cli

see https://github.com/watson/ci-info/

• #7658 Module Unification Addon blueprint @cibernox
• #7490 Module Unification Addons @ember-cli
• #7660 improve logic for if addon is module-unification @iezer
• #7667 MU addons must generate a MU dummy app @cibernox
• #7678 Use a recent release of Ember canary for MU @ember-cli

Module Unification continues...

[Turbo87]

• #7676 Deprecate ember-cli-babel 5.x @raytiley

Babel 6 support has been out for a long time now and works quite well. Babel 5 support is deprecated and will be dropped soon.

[kennethlarsen]

• Calling array.get('@each') is deprecated. @each may only be used as dependency key.
• The private APIs propertyWillChange and propertyDidChange will be removed after the first LTS of the 3.x cycle. You should remove any calls to propertyWillChange and replace any calls to propertyDidChange with notifyPropertyChange. This applies to both the Ember global version and the EmberObject method version.

For example, the following:

Ember.propertyWillChange(object, 'someProperty');
doStuff(object);
Ember.propertyDidChange(object, 'someProperty');

object.propertyWillChange('someProperty');
doStuff(object);
object.propertyDidChange('someProperty');

Should be changed to:

doStuff(object);
Ember.notifyPropertyChange(object, 'someProperty');

doStuff(object);
object.notifyPropertyChange('someProperty');

If you are an addon author and need to support both Ember applications greater than 3.1 and less than 3.1 you can use the polyfill ember-notify-property-change-polyfill

[kennethlarsen]

• Use of Ember.Logger is deprecated. You should replace any calls to Ember.Logger with calls to console. Read more about this deprecation on the deprecation page.
• The Router#route private API has been renamed to Router#_route to avoid collisions with user-defined
  properties or methods. Read more about this deprecation on the deprecation page.
• Use defineProperty to define computed properties. Read more about this deprecation on the deprecation page.

[kennethlarsen]

Three

[kennethlarsen]

Ember 3.1 is a minor release containing several new features and bug fixes. It includes a bump of Glimmer VM, Ember's rendering implementation, to version 0.30.5.

ES5 Getters for Computed Properties

Ember's object system has long used set and get to access properties. These APIs came from the codebase's origins in SproutCore, and predated ES5'sdefineProperty. In recent years native JavaScript setter and getter implementations have become fast and mature.

Starting in Ember 3.1 (and described in RFC281) you are now able to read the value of a computed property using a native ES5 getter. For example, this component which uses computed properties:

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

export default Component.extend({

  name: computed('firstName', 'lastName', function() {
    return `${this.get('firstName')} ${this.get('lastName')}`;
  }),

  message: computed('name', function() {
    return `Hello ${this.get('name')}!`;
  });

});

Can be re-written using ES5 getters:

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

export default Component.extend({

  name: computed('firstName', 'lastName', function() {
    return `${this.firstName} ${this.lastName}`;
  }),

  message: computed('name', function() {
    return `Hello ${this.name}!`;
  })

});

Legacy get features are not deprecated or removed in 3.1. In fact there are
several cases where you must still use get:

• If you are calling get with a chained path. For example in this.get('a.b.c') if b is undefined the return value is undefined. Converting this
  to this.a.b.c when b is undefined would instead raise an exception.
• If your object is using unknownProperty you must continue to use get. Using an ES5 getter on an object with unknownProperty will cause an assertion failure in development.
• Ember Data returns promise proxy objects when you read an async relationship and from other API. Ember proxy objects, including promise proxies, still require that you call get to read values.

With these caveats in mind, how should you know if you can convert a get call to a native getter? If you have code where get is called on this you likely can convert it. If you have a get on another object, anything.get('foo'), you should exercise caution when converting to a native getter.

The community-provided es5-getter-ember-codemod is a great way to convert your existing codebase to ES5 getters. It follows the conservative guidelines and only converts this.get. Note that it cannot make all possible conversions to the new API, nor can it ensure 100% of the conversions it makes are correct. If your app has poor test coverage or you lack any confidence in your ability to make regression checks, a manual and gradual conversion process may be more appropriate.

Thanks to Chris Garrett for pushing forward work on ES5 getters with support from Godfrey Chan, Robert Jackson, and Kris Selden). Thanks to Jonathan Jackson for his work on the codemod.

Introducing Optional Features

Because major releases of Ember are not supposed to make breaking changes without prior deprecation, the project has been extremely conservative about changing behaviors that don't have a clear deprecation path. As a result, we've had several quirks of the framework linger into the 3.x series.

To give the project a path forward when a breaking change is mandatory, we've released the @ember/optional-features addon. Today this addon is opt-in via installation as an NPM dependency. In a future release of Ember it will become part of the default application blueprint.

This addon does nothing by default, but provides a command-line interface to enable and disable breaking changes in Ember. Two optional features are being introduced in Ember 3.1.

To install ember-optional-features:

ember install @ember/optional-features

Thanks to Godfrey Chan and Robert Jackson for their work on the optional features system.

New Optional Feature: Application Template Wrapper

Ember applications have long created a wrapping div around their rendered content: <div class="ember-view">. With ember-optional-features, this functionality can now be disabled:

ember feature:disable application-template-wrapper

Disabling this feature will stop Ember from creating a div around the application. This change may require alterations to your application's CSS, or to any other code that depends upon the presence of the div.

Additionally, enabling this feature will prompt you to optionally run a codemod to add the application div to the application.hbs of your application.

Although disabling this feature will eventually be the default for Ember, leaving the feature enabled is not deprecated in this release. You can read more details about this optional feature and the motivations for introducing it in RFC #280.

New Optional Feature: Template-only Glimmer Components

Ember components implicitly create an element in the DOM where they are invoked, and the contents of their templates are then treated as "innerHTML" inside that DOM element. For example, this component template:

Hello World!

When invoked as:

<section>
  {{hello-world}}
</section>

Would render with an implicit div:

<section>
  <div class="ember-view">
    Hello World!
  </div>
</section>

The treatment of templates as "innerHTML" in Ember makes several parts of the framework's API harder to learn. For example, setting a class on an element in a template is straight forward, and any developer comfortable with HTML should be comfortable doing so. However adding a class to the implicit component div is more difficult, requiring the developer to create a JavaScript file for the component and use the classNames property.

To resolve this tension, Glimmer components shift templates to be treated as "outerHTML". There is no implicit div. All the DOM elements created by the renderer are in a template.

The "Template-only Glimmer Component" feature provides a first practical step in this direction. You can enable this feature by running:

ember feature:enable template-only-glimmer-components

Once enabled, any component template file without a corresponding JavaScript file will behave like "outerHTML". For example the component file:

Hello World!

Without any corresponding JavaScript file, and invoked as:

<section>
  {{hello-world}}
</section>

Would render without an implicit div, as follows:

<section>
  Hello World!
</section>

Enabling this feature may require changes to your application's CSS, or to any other code dependent upon the presence of divs for JavaScript-free components. In practice, most applications and nearly all addons use the Ember CLI generators for new components, which include a JavaScript file. If your application has template-only components which rely on a backing EmberComponent class, for example, if they have an injected-by-type service, note that they would also lose access to that backing class.

However, enabling this feature will prompt you to optionally run a codemod which creates backing classes for all template-only components, meaning both the implicit div and backing class are retained.

Although enabling this feature will eventually be the default for Ember, leaving the feature disabled is not deprecated in this release. You can read more details about this optional feature and the motivations for introducing it in RFC #278.

Positional Params Bug Fix

Ember introduced contextual components in Ember 2.3. Contextual components close over arguments and are intended to do so in a manner consistent with closures in JavaScript.

As the implementation of contextual components has been refined in the Glimmer VM, a notable discrepancy has been noticed in how they handle positional params. Given the following template:

{{#with (component 'x-foo' 1 2 3) as |comp|}}
  {{component comp 4 5 6}}
{{/with}}

The params of 4, 5, 6 would override those of 1, 2, 3. Normal closure implementations would instead have appended the arguments to result in a positional argument list of 1, 2, 3, 4, 5, 6.

In Ember 3.1 we've corrected the implementation to act like a proper closure. In researching the impact of this breaking bug fix we found no known public addons or applications which would be impacted.

For more information about this change see
emberjs/ember.js#15287.

[kennethlarsen]

#5273 client-side-delete semantics unloadRecord

[kennethlarsen]

#5230 [BUGFIX] enable lazy-relationship payloads to work with polymorphic relationships

[kennethlarsen]

• Ember.Map was a private API provided by Ember (for quite some time). Unfortunately, ember-data made Ember.Map part of its public API surface via documentation blocks. Ember.Map will be deprecated and removed from Ember "soon" (Remove Ember.Map, Ember.MapWithDefault and Ember.OrderedSet rfcs#237) and we would like to confirm that Ember Data will work without deprecation before and after that happens.Ember.Map differs from native Map in a few ways:
  • Ember.Map has custom copy and isEmpty methods which are not present in native Map
  • Ember.Map adds a static create method (which simply instantiates itself with new Ember.Map())
  • Ember.Map does not accept constructor arguments
  • Ember.Map does not have:
    • @@species
    • @@iterator
    • entries
    • values
      This implementation adds a deprecated backwards compatibility for:
  • copy
  • isEmpty

This is needed because Map requires instantiation with new and by default Babel transpilation will do superConstructor.apply(this, arguments) which throws an error with native Map. The desired code (if we lived in an "only native class" world) would be:

export default class MapWithDeprecations extends Map {
  constructor(options) {
    super();
    this.defaultValue = options.defaultValue;
  }
  get(key) {
    let hasValue = this.has(key);
    if (hasValue) {
      return super.get(key);
    } else {
      let defaultValue = this.defaultValue(key);
      this.set(key, defaultValue);
      return defaultValue;
    }
  }
}

[MelSumner]

@kennethlarsen

• values
  This implementation adds a deprecated backwards compatibility for:
• copy
• isEmpty

is "This" referring to values?

[kennethlarsen]

No deprecations

[MelSumner]

can you add responsive: true please.

[MelSumner]

(per @locks request) Merged more comments into the draft. @Turbo87 @kennethlarsen please review though- I've updated some of the outline numbering in the sections to enhance readability.

[Turbo87]

@MelSumner we should probably turn my list of PRs into prose though before publishing 😉

[Turbo87]

missing a newline after "blueprints & addons"

[Turbo87]

all lowercase please 🙏

[Turbo87]

thanks for working on this @MelSumner!! ❤️