@ember-data_canary-features Module
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
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:
# 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:
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:
if (macroCondition(dependencySatisfies('@ember-data/store', '5.0'))) {
// do thing
}
This module provides the following classes: