Feature flags

A feature flag is a remote configuration key whose value is 'true' or 'false'. You change the value in the dashboard, and every client reads the new value at its next refresh. Feature flags use Analytics Web (@grainql/analytics-web). Grain Tag has no remote configuration. Read Remote configuration for the cache-first flow and the methods.

The pattern

Read the flag, compare it with the string 'true', and show one of two branches. Every configuration value is a string, so enabled === true is always false.

import { useConfig } from '@grainql/analytics-web/react';

function App() {
  const { value: newUIEnabled } = useConfig('new_ui_enabled');

  return newUIEnabled === 'true' ? <NewUI /> : <LegacyUI />;
}

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({ tenantId: 'your-tenant-id' });

if (grain.getConfig('new_ui_enabled') === 'true') {
  showNewUI();
} else {
  showLegacyUI();
}

In the dashboard, set new_ui_enabled to true to turn the feature on and to false to turn it off.

A kill switch

A kill switch is a flag that is on by default and that you turn off when a feature fails in production. Compare with 'false', so that a missing value keeps the feature on.

function ChatWidget() {
  const { value: chatEnabled } = useConfig('chat_enabled');

  if (chatEnabled === 'false') {
    return null;
  }

  return <ChatComponent />;
}

If the chat service stops, set chat_enabled to false in the dashboard. Every client hides the widget at its next refresh. The default refresh interval is 300000 ms. Read Remote configuration to change it.

A gradual rollout

The code of a gradual rollout is the pattern above. The rollout happens in the dashboard, where a rule returns 'true' for a percentage of users.

function BetaFeature() {
  const { value: enabled } = useConfig('beta_feature_enabled');

  if (enabled !== 'true') {
    return null;
  }

  return <BetaFeatureContent />;
}

Increase the percentage in steps, for example 5%, 25%, 50%, and 100%. Read the metrics of each step before the next one. When the flag is at 100% and stable, remove the flag from the code and delete the key.

A user-specific flag

Pass user properties with the read. A rule in the dashboard evaluates the properties and returns the value for this user. Every property value is a string.

function PremiumFeature({ plan }: { plan: string }) {
  const { value: enabled } = useConfig('premium_feature', {
    properties: { plan }
  });

  if (enabled !== 'true') {
    return <UpgradePrompt />;
  }

  return <FeatureContent />;
}

In the dashboard, create a rule for premium_feature: if plan equals premium, return true. Every other user receives the default value. Read Personalization for rules on more than one property.

Defaults

Set a default for every flag in defaultConfigurations. A client reads the default before the first response from the API. It also reads the default when the API is not reachable.

<GrainProvider
  config={{
    tenantId: 'your-tenant-id',
    defaultConfigurations: {
      new_ui_enabled: 'false',
      chat_enabled: 'true',
      beta_feature_enabled: 'false'
    }
  }}
>
  <App />
</GrainProvider>

Rules for defaults:

A new feature defaults to 'false'.
A kill switch defaults to 'true'.
Name a flag after the feature and its state: new_dashboard_enabled, not feature1.
Write in the dashboard what the flag controls and when to delete it.

Testing

Both branches of a flag run in production, so both need a test. Pass a client with the flag in defaultConfigurations to the provider, one test per value.

import { createGrainAnalytics } from '@grainql/analytics-web';
import { GrainProvider } from '@grainql/analytics-web/react';

function renderWithFlag(value: string) {
  const client = createGrainAnalytics({
    tenantId: 'your-tenant-id',
    defaultConfigurations: { new_ui_enabled: value }
  });

  return render(
    <GrainProvider client={client}>
      <App />
    </GrainProvider>
  );
}

renderWithFlag('true');
renderWithFlag('false');

To measure a feature before a full rollout, send an event when the feature shows and when the user uses it. Read Track an event.

function NewFeature() {
  const { value: enabled } = useConfig('new_feature_enabled');
  const track = useTrack();

  useEffect(() => {
    if (enabled === 'true') {
      track('feature_viewed', { feature: 'new_feature' });
    }
  }, [enabled, track]);

  if (enabled !== 'true') {
    return null;
  }

  return (
    <button onClick={() => track('feature_used', { feature: 'new_feature' })}>
      Use feature
    </button>
  );
}

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

The pattern

A kill switch

A gradual rollout

A user-specific flag

Defaults

Testing

​The pattern

​A kill switch

​A gradual rollout

​A user-specific flag

​Defaults

​Testing

The pattern

A kill switch

A gradual rollout

A user-specific flag

Defaults

Testing