PostHog Flags SDK Example

The PostHog Flags SDK Example is a Next.js boilerplate from the Vercel examples library that shows how to connect PostHog feature flags with the Flags SDK and the @flags-sdk/posthog adapter, using the Flags Explorer for local flag overrides.

What is the PostHog Flags SDK Example?

This template is a reference implementation that combines PostHog, the Flags SDK, and Vercel's Flags Explorer. It runs on Next.js and is intended for deployment to Vercel. As input, it requires environment variables for a PostHog project (POSTHOG_PROJECT_API_KEY and POSTHOG_HOST) and a FLAGS_SECRET for the Flags Explorer; as output it produces a demo website with two e-commerce banners gated by the feature flags summer_sale and free_delivery. The example is maintained by Vercel as part of their public examples repository.

Key Features

• PostHog flag integration — The template uses the Flags SDK with the @flags-sdk/posthog adapter to evaluate two feature flags, each configured in PostHog to roll out to 50% of visitors.
• Flags Explorer support — After running vercel link and vercel env pull, developers can use the Vercel Toolbar's Flags Explorer to force flags on or off locally, provided FLAGS_SECRET is set.
• One-click Vercel deployment — The included Deploy button clones the repo, creates a Vercel project, installs the PostHog integration from the Vercel Marketplace, and prompts for a base64-encoded 32-byte FLAGS_SECRET.
• Local evaluation option — Setting POSTHOG_SECRET_KEY (a phs_... key) lets the PostHog adapter evaluate flags locally instead of making a remote call for each flag check.
• Manual setup path — For those avoiding the Marketplace integration, the template documents how to manually set POSTHOG_PROJECT_API_KEY, POSTHOG_HOST, and FLAGS_SECRET, plus POSTHOG_PERSONAL_API_KEY and POSTHOG_PROJECT_ID for Flags Explorer.
• Two flag keys in flags.ts — The flag identifiers (summer_sale and free_delivery) are defined in a single flags.ts file, making it easy to adjust or extend.
• E-commerce banner demo — The example UI renders a "Summer Sale" banner and a "Free Shipping" banner, each independently controlled by its flag.

Who is it for?

• Next.js developers who want a working reference for integrating PostHog feature flags with the Flags SDK.
• E-commerce teams running staged rollouts or A/B tests on promotional content like sale banners.
• Vercel users who want to explore the Flags Explorer workflow with a real third-party provider.
• Platform engineers evaluating feature flag tooling who need a minimal, deployable proof of concept.

What can you do with the PostHog Flags SDK Example?

• Run a 50% rollout experiment: In PostHog, set both flags to 50% and observe how visitors are split between seeing and not seeing each banner.
• Toggle flags from the Vercel Toolbar: Link your local project with vercel link, pull env vars with vercel env pull, and use Flags Explorer to override flag values during development.
• Deploy with an auto-configured PostHog integration: Use the one-click deploy button to install the PostHog integration and have POSTHOG_PROJECT_API_KEY and POSTHOG_HOST set automatically.
• Add your own flags: Since the flag keys live in flags.ts, you can extend the demo with additional flags by editing that file and creating matching flags in PostHog.

How does it work?

At runtime, the Flags SDK evaluates the feature flags through the PostHog adapter, which either queries PostHog remotely or uses local evaluation when POSTHOG_SECRET_KEY is present. The resulting boolean values control whether each banner is rendered. For the Flags Explorer to override flags, the project must be linked to Vercel and the FLAGS_SECRET environment variable must match the one generated at deployment.

Pros and cons

• Pros: One-click deploy with automatic PostHog integration; supports both remote and local evaluation; integrates with Vercel's Flags Explorer for developer-friendly flag toggling; clear documentation for manual setup.
• Cons: The feature flags themselves must be created manually in PostHog before the banners appear — the template only provides the keys; using Flags Explorer requires the project to be linked locally and environment variables pulled.

FAQ

Do I need a PostHog account to use this template?

Yes. The template needs a PostHog project to host the feature flags and provide the POSTHOG_PROJECT_API_KEY and POSTHOG_HOST values. You also need to create two feature flags, summer_sale and free_delivery, in PostHog.

What is FLAGS_SECRET used for?

FLAGS_SECRET is a base64-encoded 32-byte random value that the Flags Explorer uses to securely overwrite feature flags. The template prompts you to generate it during deployment, or you can set it yourself in a manual setup.

Can I evaluate flags locally instead of calling PostHog for each check?

Yes, set POSTHOG_SECRET_KEY (the feature flags secret key, starting with phs_) and the PostHog adapter will evaluate flag values locally. This reduces latency but requires the secret key to be kept secure.

How do I see the banners in the demo?

By default the two flags are configured to roll out to 50% of users, so approximately half of the visitors will see each banner. You can change the rollout percentage in PostHog or force flag values using Vercel's Flags Explorer.