Standardised API for feature toggling

Downloads in past


4.0.0a year ago3 years agoMinified + gzip package size for @cazoo/toggles in KB


- features
- [market-specific features](#market-specific-features)
- treatments - Commit messages
- [Type](#type)
- [Context](#context)
- [Examples](#examples)
Simple wrapper on top of environment variables to standardise feature toggling.
This is a universal package for both the browser and node.
At this point this package is more about estabilishing a convention rather being super useful. In the future this can be extended with pluggable Providers, like cookies or any service that stores key-value pairs.


npm install @cazoo/toggles --save

Basic usage


process.env = {
    FEATURE_LASER: 'on',

import toggles from '@cazoo/toggles';

const { featureIsEnabled } = toggles.create();


if (featureIsEnabled('LASER')) {
    // use laser
} else {
    // don't use laser

market-specific features

When a feature toggle value is a stringified object, this object's keys are treated as markets and its values - as toggle values for each market.
It is possible to declare also a default value that will be used for markets where the toggle is not explicitly set.
process.env = {
    FEATURE_LASER: '{"gb":"off","default":"on"}',

featureIsEnabled('LASER', 'gb')
// false

featureIsEnabled('LASER', 'fr')
// true - because the default value is set to 'on'

// true - the default value is used also when queried without a market 

featureIsEnabled('DEATH_STAR', 'gb')
// true - 'on' is equivalent to '{"default":"on"}'


process.env = {
    EXPERIMENT_LASER: JSON.stringify( {treatment: "on"} );
    EXPERIMENT_DEATH_STAR: JSON.stringify( {treatment: "off", config: JSON.stringify({luke: "I'm your father"}) );

import toggles from '@cazoo/toggles';

const { getTreatment, getAllExperiments } = toggles.create();


if (getTreatment('LASER').treatment === "on") {
    // use laser
} else {
    // don't use laser

//declare your config interface
interface config {
    luke : string

if(toggle.getTreatment("DEATH_STAR").config as config) {
    // if config is defined

const abSetup = getAllExperiments();
// array of experiments e.g.
// [
//     {
//         testName: "LASER",
//         treatment: "on"
//     },
//     {
//         testName: "DEATH_STAR",
//         treatment: "off",
//         config: {luke: "I'm your father"}
//     }
// ]

More usages

Please, refer to the integration.test.ts and integration.browser.test.ts for all the usages. They are intended to be a living documentation for the user.


Releases are created by semantic-release, which checks all the commit messages since the last release to determine what the new version number should be.

Commit messages

To trigger a release, your commits need to follow the Angular Commit Message Conventions, meaning they need to be written in this pattern:
type(context): message


Commits using the types feat, fix or perf will appear in the changelogs. However, any commit with BREAKING CHANGE in the body will also appear in the changelog, regardless of the type.
| Type | Release type | Description | | - | - | - | | feat | Minor (0.X.0) | A new feature | | fix | Patch (0.0.X) | A bug fix | | perf | Patch (0.0.X) | A code change that improves performance | | refactor | - | A code change that neither fixes a bug nor adds a feature | | test | - | Adding missing tests or correcting existing tests | | docs | - | Documentation only changes | | ci | - | Changes to our CI configuration files and scripts (example: CircleCI, BrowserStack, SauceLabs) | | build | - | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |


For the context, we add the Jira ticket number. It's optional but good to have since the release logs are generated from the commits.


| Commit message | Release type | | - | - | | perf(DR-4567): remove graphiteWidth option from Pencil

BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons. | Major (X.0.0) | | feat(DR-4567): add 'graphiteWidth' option to Pencil | Minor (0.X.0) | | fix(DR-4567): stop graphite breaking when too much pressure applied to Pencil | Patch (0.0.X) |
šŸ’” To add a body to your commit message, you can use git commit -m "TITLE" -m "BODY"