Intermediate
How to bootstrap flags for performance on PostHog
Quick Answer
Bootstrap flags in PostHog by pre-loading flag values during initialization to eliminate network delays and improve performance. This involves fetching flag values server-side or from cache and passing them to the PostHog client during initialization.
Prerequisites
- PostHog account with project access
- Feature flags already created in your project
- Basic understanding of JavaScript/SDK implementation
- Access to your application's codebase
1
Enable bootstrap flags in PostHog project settings
Navigate to your PostHog project and go to Settings > Project > Feature Flags. Scroll down to find the Bootstrap flags section and toggle it On. This enables the bootstrap functionality for your project and allows you to retrieve flag values via API.
Tip
Bootstrap flags work best when you have a limited number of flags to avoid large payload sizes.
2
Get your project's bootstrap endpoint
In the same Feature Flags settings page, copy the Bootstrap API endpoint URL. It will look like:
https://app.posthog.com/decide/?v=3&token=YOUR_PROJECT_API_KEY. You'll use this endpoint to fetch flag values server-side before initializing your PostHog client.Tip
Store this endpoint URL in your environment variables for easy configuration across environments.
3
Fetch bootstrap flag values server-side
Make a server-side request to the bootstrap endpoint with the user's distinct ID. Example using Node.js:
const response = await fetch(`https://app.posthog.com/decide/?v=3&token=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
api_key: API_KEY,
distinct_id: userId,
groups: userGroups // optional
})
});
const data = await response.json();
const bootstrapFlags = data.featureFlags;Tip
Cache these flag values for a short period (1-5 minutes) to reduce API calls and improve performance further.
4
Initialize PostHog client with bootstrap flags
Pass the fetched flag values to your PostHog client initialization using the
bootstrap option:posthog.init('YOUR_PROJECT_API_KEY', {
api_host: 'https://app.posthog.com',
bootstrap: {
featureFlags: bootstrapFlags,
distinctID: userId
}
});5
Verify bootstrap flags are working
Check your browser's Network tab in Developer Tools. You should see fewer
/decide/ API calls after implementing bootstrap flags. Additionally, test that posthog.isFeatureEnabled('your-flag-name') returns values immediately without waiting for network requests to complete.Tip
Use PostHog's debug mode by adding ?__posthog_debug=1 to your URL to see detailed flag loading information.
6
Handle bootstrap flag updates
Set up automatic flag refresh for long-running sessions by configuring the
feature_flag_request_timeout_ms option:posthog.init('YOUR_PROJECT_API_KEY', {
bootstrap: { featureFlags: bootstrapFlags },
feature_flag_request_timeout_ms: 300000 // 5 minutes
});Tip
Consider implementing WebSocket connections or server-sent events for real-time flag updates in critical applications.
7
Monitor bootstrap performance impact
Navigate to Insights in your PostHog dashboard and create a new trend analysis. Track events like
$feature_flag_called and monitor the $feature_flag_response property to measure the performance improvement. Set up alerts for any increase in flag evaluation latency that might indicate bootstrap issues.Tip
Compare page load times before and after implementing bootstrap flags to quantify the performance improvement.
Troubleshooting
Bootstrap flags not loading or showing as undefined
Verify that your Project API Key is correct and that the bootstrap endpoint is returning data. Check the network response in browser dev tools and ensure the
distinct_id parameter matches between server-side fetch and client initialization.Bootstrap flags showing outdated values
Reduce your server-side cache duration or implement cache invalidation when flags are updated in PostHog. You can also force a flag refresh by calling
posthog.reloadFeatureFlags() when needed.Large bootstrap payload affecting page performance
Limit bootstrap flags to only critical flags needed for initial page render. Use PostHog's flag filtering options in the bootstrap API call to fetch only specific flags:
{ api_key: API_KEY, distinct_id: userId, only_evaluate_locally: true }Bootstrap failing for anonymous users
Ensure you're generating and maintaining consistent
distinct_id values for anonymous users both server-side and client-side. Consider using session-based IDs or UUIDs stored in cookies for anonymous user consistency.Ready to get started with PostHog?
Put this tutorial into practice. Visit PostHog and follow the steps above.
Visit PostHog →