Client-side bootstrapping

Note: Bootstrapping feature flags is only available in our JavaScript web and React Native SDKs.

Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This is 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 initialize PostHog with precomputed values until PostHog has had a chance to fetch them. This is called bootstrapping.

To bootstrap PostHog with feature flags, use the bootstrap key in the initialization config and add feature flag values to it:

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

Setting the correct flag values

To ensure you are bootstrapping PostHog with the correct flag values, we recommend fetching the flags values from your server alongside the page load request, and then passing them to your frontend.

You can do this by:

When receiving a frontend request, fetch all the feature flags for the user by calling getAllFlags().
Return the frontend request with the flags values in the response.
On the frontend, get the flag values from the response and add them to the bootstrap key in the PostHog initialization.

Tip: to ensure your request is as quick as possible, use local evaluation on your server.

Bootstrapping with a distinct ID

The bootstrap object has two optional arguments: distinctID and isIdentifiedID.

distinctID enables you to set distinct ID of the user during PostHog's initialization. This is useful when you want to ensure the distinct ID on your frontend is the same as the distinct ID that you called getAllFlags() with on your server. It is strongly recommended to include it.

Note: The only case where it doesn't make sense to include the distinctID is when you're bootstrapping identified users only, and you call identify for these users right on load. Here, if you pass in the distinctID to bootstrap, identify will not connect your existing anonymous ID, since it's replaced by the bootstrapped ID.

isIdentifiedID ensures that the distinctID 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: 'distinct_id_of_your_user',
        isIdentifiedID: true,
        featureFlags: {
            'flag-1': true,
            'variant-flag': 'control',
            'other-flag': false,
        },
    },
})

Setting the correct flag values

Bootstrapping with a distinct ID

Examples

Questions?

Was this page useful?

Early access feature management