How to bootstrap flags for performance on PostHog

intermediate 8 min read Updated 2026-03-18

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.

Try PostHog Full PostHog Review

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

Step-by-Step Instructions

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.

Bootstrap flags work best when you have a limited number of flags to avoid large payload sizes.

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.

Store this endpoint URL in your environment variables for easy configuration across environments.

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;

Cache these flag values for a short period (1-5 minutes) to reduce API calls and improve performance further.

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
  }
});

This prevents the client from making additional network requests for flag values during initialization.

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.

Use PostHog's debug mode by adding ?__posthog_debug=1 to your URL to see detailed flag loading information.

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
});

This ensures flags are periodically updated even when using bootstrap values.

Consider implementing WebSocket connections or server-sent events for real-time flag updates in critical applications.

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.

Compare page load times before and after implementing bootstrap flags to quantify the performance improvement.

Common Issues & 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.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official PostHog website before purchasing.

Visit PostHog View PostHog Pricing