@procore/web-sdk-feature-toggle

Web Platform Feature Toggle

Utilities for managing feature toggles in Procore.

Installation

yarn add @procore/web-sdk-feature-toggle

Migration from LaunchDarkly SDK

This document describes how to migrate from the LaunchDarkly SDK to the Web Platform Feature Toggle SDK.

Usage

Setting up

import { FeatureToggleProvider } from '@procore/web-sdk-feature-toggle';

function Index() {
  return (
    <FeatureToggleProvider
      apiKey="my-launchdarkly-env-key"
      context={{
        user: {
          projectId: '1',
          companyId: '2',
          locale: 'en-US',
          email: '[e-mail]', // required field. If email is not available - use other unique identifier (e.g. userId). If user is not signed in - use uuid
        },
      }}
    >
      <App />
    </FeatureToggleProvider>
  );
}

Accessing feature flags

import { useFeatureFlag } from '@procore/web-sdk-feature-toggle';

function MyComponent() {
  const myFeatureFlagValue = useFeatureFlag('my-feature-flag', 'default-value');
  // ...
}

Changing context

The FeatureToggleProvider is designed in a way that when the context changes, all components that use feature flags will re-evaluate the flags. However, if you like to manually update the context, you can use the updateContext method from the FeatureToggleClient instance.

import { useFeatureToggleClient } from '@procore/web-sdk-feature-toggle';

function MyComponent() {
  const { updateContext } = useFeatureToggleClient();

  // `myFeatureFlagValue` will be re-evaluated when the context changes
  const myFeatureFlagValue = useFeatureFlag('my-feature-flag', 'default-value');

  return (
    <button
      type="button"
      onClick={() => {
        updateContext({
          user: {
            email: '[e-mail]', // required field. If email is not available - use other unique identifier (e.g. userId). If user is not signed in - use uuid
            projectId: '3',
            companyId: '4',
            locale: 'en-GB',
          },
        });
      }}
    >
      Change context
    </button>
  );
}

API

Types

type UserContext = {
  companyId?: string;
  email: string; // required field. If email is not available - use other unique identifier (e.g. userId). If user is not signed in - use uuid
  locale?: string;
  projectId?: string;
  [key: string]: unknown;
};

interface FeatureToggleContext {
  user?: UserContext;
  [key: string]: unknown;
}

type FeatureFlagValue = unknown;
type FeatureFlags = Record<string, FeatureFlagValue>;

FeatureToggleClient

constructor

Create a new instance of the FeatureToggleClient.

function constructor(apiKey: string, context: FeatureToggleContext): void;

setContext

Set the context for the FeatureToggleClient.

function setContext(context: FeatureToggleContext): Promise<void>;

getFeatureFlag

Get the value of a feature flag.

getFeatureFlags

Get the values of all feature flags.

function getFeatureFlag(key: string): FeatureFlagValue;

__getClient (for advanced use cases or debugging)

Get the LaunchDarkly client.

function __getClient(): LDClient;

FeatureToggleProvider

React context provider for the feature toggle client instance. Prop waitTillReady can be used to only render children once the client is initialized.

import {
  FeatureToggleClient,
  FeatureToggleProvider,
  useFeatureFlag,
} from '@procore/web-sdk-feature-toggle';
import { App } from './App';

function Index() {
  return (
    <FeatureToggleProvider
      waitTillReady // optional, default: true
      apiKey="my-launchdarkly-env-key"
      context={{
        user: {
          projectId: '1',
          companyId: '2',
          locale: 'en-US',
          email: '[e-mail]', // required field. If email is not available - use other unique identifier (e.g. userId). If user is not signed in - use uuid
        },
      }}
    >
      <App />
    </FeatureToggleProvider>
  );
}

useFeatureFlag

React hook to get the value of a feature flag.

function useFeatureFlag(key: string): FeatureFlagValue;

useFeatureFlags

React hook to get the values of all feature flags.

function useFeatureFlags(): Record<string, FeatureFlagValue>;

useFeatureToggleClient

React hook to get the feature toggle client instance.

function useFeatureToggleClient(): FeatureToggleClient;

Local Development

To run storybook with a real LaunchDarkly client, you need to set the LD_ENV_ID environment variable in .env file.

To use LaunchDarkly mock, add the following code to storybook/main.js:

module.exports = {
  webpackFinal: (config) => {
    config.resolve.alias['launchdarkly-js-client-sdk'] = require.resolve(
      '../src/__tests__/launchdarkly-js-client-sdk'
    );
    return config;
  },
};

Support

#team-ui-foundations