Documentation / @warp-drive/build-config / canary-features

Canary Features requires canary

WarpDrive allows users to test upcoming features that are implemented but not yet activated in canary builds.

Typically these features represent work that carries higher risk of breaking changes, or are not yet fully ready for production use.

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, beginning the process of it landing in a stable release.

Installing Canary

To test a feature guarded behind a flag, you MUST be using a canary build.

Canary builds are published to npm and can be installed using a precise tag (such as @warp-drive/core@5.6.0-alpha.1) or by installing the latest dist-tag published to the canary channel.

Because WarpDrive packages operate on a strict lockstep policy with each other, you must install the matching canary version of all WarpDrive packages.

Below is an example of installing the latest canary version of all the primary packages that are part of the WarpDrive project. Add/remove packages from this list to match your project.

pnpm

pnpm add -E @ember-data/store@canary \
  @ember-data/json-api@canary \
  @ember-data/debug@canary \
  @ember-data/graph@canary \
  @ember-data/request@canary \
  @ember-data/request-utils@canary \
  @warp-drive/schema-record@canary \
  @warp-drive/build-config@canary \
  @warp-drive/core-types@canary;

npm

npm add -E @ember-data/store@canary \
  @ember-data/json-api@canary \
  @ember-data/debug@canary \
  @ember-data/graph@canary \
  @ember-data/request@canary \
  @ember-data/request-utils@canary \
  @warp-drive/schema-record@canary \
  @warp-drive/build-config@canary \
  @warp-drive/core-types@canary;

yarn

yarn add -E @ember-data/store@canary \
  @ember-data/json-api@canary \
  @ember-data/debug@canary \
  @ember-data/graph@canary \
  @ember-data/request@canary \
  @ember-data/request-utils@canary \
  @warp-drive/schema-record@canary \
  @warp-drive/build-config@canary \
  @warp-drive/core-types@canary;

bun

bun add --exact @ember-data/store@canary \
  @ember-data/json-api@canary \
  @ember-data/debug@canary \
  @ember-data/graph@canary \
  @ember-data/request@canary \
  @ember-data/request-utils@canary \
  @warp-drive/schema-record@canary \
  @warp-drive/build-config@canary \
  @warp-drive/core-types@canary;

Activating a Feature

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

setConfig(app, __dirname, {
  features: {
    FEATURE_A: false, // utilize existing behavior
    FEATURE_B: true // utilize the new behavior
  }
})

by setting an environment variable:

# Activate a single flag
export WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG;

# Activate multiple flags by separating with commas
export WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG;

# Activate all flags
export WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL;

To test a feature guarded behind a flag, you MUST be running a development build.

Preparing a Project to use a Canary Feature

For most projects and features, 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
}

For more complex projects and migrations, configure @warp-drive/build-config/babel-macros

The current list of features used at build time for canary releases is defined below.

💡 If empty there are no features currently gated by feature flags.

The valid values are:

• true | The feature is enabled at all times, and cannot be disabled.
• false | The feature is disabled at all times, and cannot be enabled.
• null | The feature is disabled by default, but can be enabled via configuration.

Variables

• JSON_API_CACHE_VALIDATION_ERRORS