Package @ember-data/canary-features

Canary Features

EmberData allows users to test features that are implemented but not yet available even in canary.

Typically these features represent work that might introduce a new concept, new API, change an API, or risk an unintended change in behavior to consuming applications.

Such features have their implementations guarded by a "feature flag", and the flag is only activated once the core-data team is prepared to ship the work in a canary release.

Installing Canary

To test a feature you MUST be using a canary build. Canary builds are published to npm and can be installed using a precise tag (such as ember-data@3.16.0-alpha.1) or by installing the latest dist-tag published to the canary channel using your javascript package manager of choice. For instance with pnpm

1

pnpm add ember-data@canary

Activating a Canary Feature

Once you have installed canary, feature-flags can be activated at build-time

by setting an environment variable:

1
2
3
4
5
6
7
8

# Activate a single flag
EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG ember build

# Activate multiple flags by separating with commas
EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build

# Activate all flags
EMBER_DATA_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build

or by setting the appropriate flag in your ember-cli-build file:

1
2
3
4
5
6
7
8

let app = new EmberApp(defaults, {
  emberData: {
    features: {
      SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature
      OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior
    }
  }
})

The "off" branch of feature-flagged code is always stripped from production builds.

The list of available feature-flags is located here

Preparing a Project to use a Canary Feature

For most projects, simple version detection should be enough. Using the provided version compatibility helpers from embroider-macros the following can be done:

1
2
3

if (macroCondition(dependencySatisfies('@ember-data/store', '5.0'))) {
  // do thing
}