React Unleash Flags

React component for Unleash or GitLab Feature Flags. This library provides a custom hook and react components to use in JavaScript or TypeScript projects.

Installation

Using NPM:

npm i --save react-unleash-flags

Configuration

The following config is required in order to fetch te flags from your Unleash or GitLab instance:

• appName (the name of the app you will be running. Eg.: 'production', 'staging')
• host (the location of the Unleash api. Eg.: ht​tps://my-unleash-url.com/api/)
• url (Deprecated! Use host instead)
• uri (the uri of the Unleash api. Eg.: /client/features) (this could be different if you want to point to an Unleash Proxy instead)
• instanceId (the unique Unleash instance ID)
• extraHttpHeaders (OPTIONAL extra http headers passed to the fetch call. For example, an Authorization header)

This configuration can be provided as an env variabe. The environment variables are:

• REACT_APP_FLAGS_CTX_APP_NAME
• REACT_APP_FLAGS_CTX_HOST
• REACT_APP_FLAGS_CTX_URL (Deprecated! Use REACT_APP_FLAGS_CTX_HOST instead)
• REACT_APP_FLAGS_CTX_URI
• REACT_APP_FLAGS_CTX_INSTANCE_ID

The configuration can also be provide as a dict. (see examples below)

<FlagsProvider> with config in env vars

import React from 'react';
import ReactDOM from 'react-dom';
import { FlagsProvider } from 'react-unleash-flags';
import App from './App';

const root = document.getElementById('root');

if (root != null) {
    ReactDOM.render((
        <FlagsProvider>
            <App />
        </FlagsProvider>
    ), cakeRoot);
}

<FlagsProvider> with config in code

import React from 'react';
import ReactDOM from 'react-dom';
import { FlagsProvider } from 'react-unleash-flags';
import App from './App';

const root = document.getElementById('root');

// we can also define the config in code instead of using env vars
const flagConfig = {
    appName: 'production',
    host: 'https://...',
    uri: '/client/features',
    instanceId: '...',
    extraHttpHeaders: {
        Authorization: 'token123'
    }
};

// or if env vars are used for Unleash Flags settings, they can be combined 
// these settings will be appended to the settings from the env variables
const flagConfig = {
    extraHttpHeaders: {
        Authorization: 'token123'
    }
};

if (root != null) {
    ReactDOM.render((
        <FlagsProvider config={flagConfig} >
            <App />
        </FlagsProvider>
    ), cakeRoot);
}

Usage

Make sure you've setup the <FlagsProvider> correctly.

Custom useFlag Hook

// load the flag using the useFlag hook
const flag = useFlag(name);

// a flag that does not exist will return undefined
if (flag && flag.enabled) {
    ...
}

React <FeatureFlag> component

Attributes:

• name: string - the name of the flag
• defaultValue (optional, default=false): boolean - the value when the flag does not exist or when it is still loading
• invert (optional, default=false): boolean - if true, the child elements will render when the feature is disabled

The <FeatureFlag> component can handle both JSX and a function as child elements:

<FeatureFlag name="test-flag">
    hello, this flag is enabled
</FeatureFlag>

<FeatureFlag name="test-flag" invert={true}>
    hello, this flag is disabled
</FeatureFlag>

<FeatureFlag name="test-flag">
    {(flag) => { console.log(flag); }}
</FeatureFlag>

Links

• Unleash (https://unleash.github.io/)
• GitLab Feature Flags (https://docs.gitlab.com/ee/user/project/operations/feature_flags.html)