Skip to main content

Feature Gates + Statsig Integration

This application supports feature gates (aka feature flags) for controlled exposure of code flow for users. We have chosen Statsig as our vendor for this integration. You can access the console by logging into the Birdy Grey project in Statsig.

How can I add a new feature gate or see what gates are supported?​

To view the list of supported feature gates in the application, we have a hardcoded registry that is viewable in app/lib/statsig/registry.ts. The GATES_REGISTRY object contains a list of supported feature gates along with their default values.

To add a new feature gate:

  1. Log into Statsig and create a new feature gate in the console
  2. The name of the new gate should follow our standard convention: h2_page-space-delimited-description. I'd recommend prefixing your description with a verb like enable, so that the boolean value associated with the gate makes logical sense.
  3. Copy the name of the established gate and add it as an entry to the GATES_REGISTRY object in the codebase, matching the default value from Statsig (usually false).

How do I use a feature gate?​

Simply call the checkGate function exported from app/lib/statsig/registry to retrieve the resolved value of your gate anywhere in the application. This works on both the client and server.

How can I override a feature gate?​

We have a few mechanisms for overridding feature gate values from the registry.

GATES_ON or GATES_OFF environment variable​

These are convenient ways to persist the enabling/disabling of a feature gate for a specific environment. Set either of these environment variables to a comma-delimited list of gate keys that you want to either enable or disable.

gatesOn or gatesOff URL search/query params​

To temporarily enable a feature gate, add either a gatesOn or gatesOff query parameter when hitting the application to force an evaluation as enabled or disabled.

How are gates evaluated?​

We have a priority order in which overrides are applied in-memory on top of the default values from the GATES_REGISTRY object. The full hierarchy (from lowest to highest priority) is as follows:

  1. GATES_REGISTRY defaults
  2. Either a cached gates cookie OR resolved values from Statsig
  3. Environment variable set overrides
  4. URL Search Parameters

Feature gates are evaluated with every request through server.ts. Once all gates have been resolved, we cache the status of the gate in a response cookie named gates. These cookies have a rolling 1-hour expiration time, meaning that if you have enabled a temporary override (via URL search param, for example) and make no requests to the backend for an hour, the cookie will expire and the gates will be re-evaluated.

How do we know that Statsig will evaluate a gate consistently for any given user?​

When checking gate values against Statsig, we are passing in a unique identifier for each user which is stored as a long-lived cookie named bg-user. Each time we call Statsig, we'll pass the same user ID through which should ensure that a user is bucketed into the same evaluation consistently (that is, unless the rules are updated on Statsig's end).