Flags SDK with PostHog

Flags SDK + PostHog

A minimal Next.js App Router example with two server-evaluated flags, adapted from the PostHog example.

The Deploy button copies only this folder. It installs published SDK packages and uses the standard Next.js build command.

Setup

Create these feature flags in your PostHog project and enable them for 100% of users:

For welcome_message, attach the JSON string payload (including the quotes) to the enabled value. The example reads it with postHogAdapter.payload. The show_banner flag reads the boolean value with postHogAdapter.

Copy .env.example to .env.local and set:

• POSTHOG_PROJECT_API_KEY: your project API key (phc_...), from PostHog project settings.
• POSTHOG_HOST: your regional API host, https://us.i.posthog.com or https://eu.i.posthog.com.
• POSTHOG_PROJECT_SECRET_API_KEY: a project secret API key (phs_...) with feature_flag:read scope, used only to load metadata in Flags Explorer.
• POSTHOG_PROJECT_ID: your numeric PostHog project ID, used by Flags Explorer.
• FLAGS_SECRET: generate a random secret with the command below. Add it to both .env.local and the matching environment in your Vercel project settings. For Development, use a regular environment variable (Config), rather than a Secret.

1
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Optionally set POSTHOG_SECRET_KEY to a feature flags secret key (phs_...) to enable local evaluation. By default, the adapter evaluates flags remotely.

The home page uses the Flags SDK's evaluate() API to evaluate both flags. Change their values in PostHog and refresh the page. Every visitor uses the same demo-user identity; replace identify in flags.ts to add user targeting.

Flags Explorer

The discovery endpoint at /.well-known/vercel/flags uses the PostHog adapter to load flag metadata from your PostHog project, including descriptions, options, and dashboard links. It is protected by FLAGS_SECRET. The page reports the evaluated values of its two flags to the toolbar.

Metadata requires POSTHOG_PROJECT_SECRET_API_KEY and POSTHOG_PROJECT_ID; missing configuration is reported as hints in Flags Explorer. The adapter derives the app host from POSTHOG_HOST. The project secret API key used for metadata does not enable local evaluation.

The Vercel Toolbar is included during local development. Link this folder with vercel link, sign in to the toolbar, and open Flags Explorer to override welcome_message or show_banner for your session without changing their values in PostHog. The local FLAGS_SECRET must match the linked project's Development value. Vercel injects the toolbar on preview deployments when enabled in project settings.

Run as a standalone project

Copy this folder, or use the Deploy button above. From the copied folder:

1
pnpm install
2
pnpm dev

Open http://localhost:3000. For a production build, run pnpm build and pnpm start. Use Node.js 22.22 or newer.

Run inside the Flags SDK repository

Configure examples/providers/posthog/.env.local as described above. From the repository root:

1
pnpm install
2
pnpm exec turbo run dev --filter=flags-sdk-posthog

The root pnpm-workspace.yaml overrides this example's flags and @flags-sdk/posthog dependencies to workspace:*. Explicit task dependencies in the root turbo.json ensure Turbo builds the local SDK and adapter before starting Next.js, since Turbo does not infer workspace links from pnpm overrides.

To build only this example and its dependencies:

1
pnpm exec turbo run build --filter=flags-sdk-posthog
2
pnpm --filter flags-sdk-posthog start

To deploy the workspace version on Vercel:

1. Import the full Flags SDK repository and set Root Directory to examples/providers/posthog.
2. Enable Include source files outside of the Root Directory in the Build Step.
3. Set Install Command to cd ../../.. && pnpm install --frozen-lockfile.
4. Set Build Command to cd ../../.. && pnpm exec turbo run build --filter=flags-sdk-posthog.
5. Add the environment variables from Setup.

When cloned independently, the root overrides are absent and the regular versions in package.json resolve from npm. No workspace files, shared TypeScript configuration, or build scripts are needed for the standalone app.