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-@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 } |