Bootstrapping & local evaluation

Client-side bootstrapping

There is a delay between loading the library and feature flags becoming available to use. This can be detrimental if you want to do something like redirecting to a different page based on a feature flag.

To have your feature flags available immediately, you can bootstrap them with a distinct user ID and their values during initialization.

posthog.init('<ph_project_api_key>', {
    api_host: '<ph_instance_address>',
    bootstrap: {
        distinctID: 'your-anonymous-id',
        featureFlags: {
            'flag-1': true,
            'variant-flag': 'control',
            'other-flag': false,
        },
    },
})

To get the flag values for bootstrapping, you can call getAllFlags() in your server-side library, then pass the values to your frontend initialization. If you don't do this, your bootstrap values might be different than the values PostHog provides.

If the distinct user ID is an identified ID (the value you called posthog.identify() with), you can also pass the isIdentifiedID option. This ensures this ID is treated as an identified ID in the library. This is helpful as it warns you when you try to do something wrong with this ID, like calling identify again.

posthog.init('<ph_project_api_key>', {
    api_host: '<ph_instance_address>',
    bootstrap: {
        distinctID: 'your-identified-id',
        isIdentifiedID: true,
        featureFlags: {
            'flag-1': true,
            'variant-flag': 'control',
            'other-flag': false,
        },
    },
})

Forcing feature flags to update

In our client-side JavaScript library, we store flags as a cookie to reduce the load on the server and improve the performance of your app. This prevents always needing to make an HTTP request, flag evaluation can simply refer to data stored locally in the browser. This is known as 'local evaluation.'

While this makes your app faster, it means if your user does something mid-session which causes the flag to turn on for them, this does not immediately update. As such, if you expect your app to have scenarios like this and you want flags to update mid-session, you can reload them yourself, by using the reloadFeatureFlags function.

posthog.reloadFeatureFlags()

Calling this function forces PostHog to hit the endpoint for the updated information, and ensures changes are reflected mid-session.

Server-side local evaluation

If you're using our server-side libraries, you can use local evaluation to improve performance instead of making additional API requests. This requires:

1. knowing and passing in all the person or group properties the flag relies on
2. initializing the library with your personal API key (created in your account settings)

Local evaluation, in practice, looks like this:

await client.getFeatureFlag(
    'beta-feature',
    'distinct id',
    {
        personProperties: {'is_authorized': True}
    }
)
# returns string or None

This works for getAllFlags as well. It evaluates all flags locally if possible, and if not, falls back to making a decide HTTP request.

await client.getAllFlags('distinct id', {
    groups: {},
    personProperties: { is_authorized: True },
    groupProperties: {},
})
// returns dict of flag key and value pairs.

Using locally

To test feature flags locally, you can open your developer tools and override the feature flags. You will get a warning that you're manually overriding feature flags.

posthog.feature_flags.override(['feature-flag-1', 'feature-flag-2'])

This will persist until you call override again with the argument false:

posthog.feature_flags.override(false)

To see the feature flags that are currently active for you, you can call:

posthog.feature_flags.getFlags()