---
title: PostHog
---

# PostHog



The [PostHog](https://posthog.com/) package provides a managed PostHog adapter for the Flags SDK.

<LearnMore icon="arrow" href="/providers">
  Learn more about Adapters
</LearnMore>

<LearnMore icon="arrow" href="https://vercel.com/templates/edge-middleware/posthog-with-flags-sdk-and-next-js" target="_blank">
  Deploy the template
</LearnMore>

## Example usage

```tsx title="flags.ts"
import { flag } from "flags/next";
import { postHogAdapter } from '@flags-sdk/posthog'
import identify from "@/lib/identify";

// Reads the flag's evaluated value. Pass the adapter uninvoked
// (`postHogAdapter`) or invoked (`postHogAdapter()`) — both work.
export const myFlag = flag<boolean>({
  key: "posthog-flag",
  adapter: postHogAdapter,
  identify,
});

export const myFlagVariant = flag<string>({
  key: "posthog-multivariate-flag",
  adapter: postHogAdapter,
  identify,
});

// Reads the flag's attached payload with `.payload`.
export const myFlagPayload = flag({
  key: "posthog-flag-with-payload",
  adapter: postHogAdapter.payload,
  defaultValue: {},
  identify,
});
```

## Getting started

Install the required dependencies:

```bash
pnpm i @flags-sdk/posthog
```

### Environment variables

**Always required**, read by `postHogAdapter`:

```bash title=".env.local"
# The regional API host, which determines where your data lives
# Settings > Project > Project API Key
POSTHOG_HOST=https://us.i.posthog.com
# or https://eu.i.posthog.com

# Your project API key
# Settings > Project > Project API Key
POSTHOG_PROJECT_API_KEY=phc_...
```

**Optional**, opts `postHogAdapter` into [local evaluation](#local-evaluation), where
flag definitions are polled in the background instead of evaluating each flag remotely:

```bash title=".env.local"
# Settings > Project > Feature flags secret key
POSTHOG_SECRET_KEY=phs_...
```

**For the [Flags Explorer](#flags-explorer)**, read by `getProviderData` only:

```bash title=".env.local"
# Settings > User > Personal API keys
POSTHOG_PERSONAL_API_KEY=phx_...
# Settings > Project > Project ID
POSTHOG_PROJECT_ID=521742
```

Import the PostHog adapter for Flags SDK, which reads `POSTHOG_PROJECT_API_KEY`, `POSTHOG_HOST` and `POSTHOG_SECRET_KEY` when it is first used:

```ts title="flags.ts"
import { postHogAdapter } from '@flags-sdk/posthog'
```

If needed, you can instead initialize the adapter with your own options by importing `createPostHogAdapter`

```ts title="flags.ts"
import { createPostHogAdapter } from '@flags-sdk/posthog'

const postHogAdapter = createPostHogAdapter({
  postHogKey: process.env.POSTHOG_PROJECT_API_KEY!,
  postHogOptions: {
    host: process.env.POSTHOG_HOST,
    // ...
  },
})
```

The `postHogAdapter` is a single callable adapter. You can pass it directly, or
invoke it — both are equivalent:

* `postHogAdapter` (or `postHogAdapter()`): resolves the flag's evaluated value. For
  a boolean flag this is a boolean; for a multivariate flag it is the variant `string`.
  Type the flag (e.g. `flag<boolean>`) to get the value type you expect.
* `postHogAdapter.payload` (or `postHogAdapter.payload()`): resolves the flag's
  attached payload.

The flag's `key` is used as the PostHog feature flag key as-is. Every flag needs an
`identify` function returning the entities the adapter evaluates against:

```ts title="lib/identify.ts"
import type { Identify } from 'flags'
import type { PostHogEntities } from '@flags-sdk/posthog'

export const identify: Identify<PostHogEntities> = async () => {
  return { distinctId: 'user-123' }
}
```

The adapter throws if `entities` is missing, so a flag without `identify` will fail at
evaluation time.

```ts title="app/flags.ts"
import { flag } from 'flags/next'
import { postHogAdapter } from '@flags-sdk/posthog'
import { identify } from '@/lib/identify'

export const exampleFlag = flag<boolean>({
  key: 'example-flag',
  defaultValue: false,
  adapter: postHogAdapter,
  identify,
})
```

Flags backed by this adapter participate in [bulk evaluation](/frameworks/next/bulk-evaluation):
`evaluate()` resolves flags that share an `identify` source through a single PostHog
request.

Then use it in your framework:

```tsx title="app/page.tsx"
import { exampleFlag } from "@/flags";

export default async function Page() {
  const exampleValue = await exampleFlag();

  return <div>Example Flag: {String(exampleValue)}</div>;
}
```

## Evaluation modes

PostHog can evaluate flags remotely or locally.

### Remote evaluation (default)

With only `POSTHOG_PROJECT_API_KEY` and `POSTHOG_HOST` set, the adapter evaluates
remotely. PostHog makes a network request for every feature flag evaluation, and each request
is billed separately. Having to make a network request for every flag evaluation
also adds latency. If you provide user ids, PostHog will look up additional properties from its database.

### Local evaluation

Setting `POSTHOG_SECRET_KEY` (`phs_...`) is the only thing that switches evaluation
modes — the default adapter enables local evaluation exactly when that key is present.

In this mode, `posthog-node` periodically fetches your flag definitions in the
background (every 30s by default) and evaluates flags in-process against those cached
definitions, avoiding a network round trip on most checks after initialization. Because evaluation happens
locally, you're responsible for providing every property the flag's release conditions
depend on.

Each background poll is billed as 10 flag requests, independent of how many checks it
serves, so for a long-running process this is usually far cheaper than paying per
check. But the poller runs per compute instance, so PostHog recommends against local
evaluation in short-lived compute, where each invocation would otherwise
start its own poller and multiply cost rather than amortize it. Use remote evaluation
there instead. You can widen the polling interval to trade slower propagation of flag
changes for lower polling cost.

With [Fluid Compute](https://vercel.com/fluid) you may see latency and cost benefits from using local evaluation.
It depends on your traffic patterns and load.

You can also enable it explicitly with `createPostHogAdapter`:

```ts title="flags.ts"
import { createPostHogAdapter } from '@flags-sdk/posthog'

const postHogAdapter = createPostHogAdapter({
  postHogKey: process.env.POSTHOG_PROJECT_API_KEY!,
  postHogOptions: {
    host: process.env.POSTHOG_HOST,
    secretKey: process.env.POSTHOG_SECRET_KEY,
    enableLocalEvaluation: true,
  },
})
```

<Callout type="info">
  `POSTHOG_PERSONAL_API_KEY` is used only by the Flags Explorer (`getProviderData`,
  below) to discover flag definitions. It is never passed to the runtime client and
  does **not** enable local evaluation.
</Callout>

The default adapter also sets `disableGeoip: true`, since the server's IP is not a good
proxy for the user's location. Use `createPostHogAdapter` if you want the GeoIP-derived
person properties.

## Flags Explorer

### How to inform the Flags Explorer about flags

You can view and override these flags using the [Flags Explorer](https://vercel.com/docs/flags/flags-explorer)

For getProviderData, you will also need a personal API key and your project ID.

```bash title=".env.local"
# Settings > User > Personal API keys
POSTHOG_PERSONAL_API_KEY=phx_...
# Settings > Project > Project ID
POSTHOG_PROJECT_ID=521742
```

```ts title="app/.well-known/vercel/flags/route.ts#next"
import { createFlagsDiscoveryEndpoint } from 'flags/next'
import { getProviderData as getPostHogProviderData } from '@flags-sdk/posthog'

export const GET = createFlagsDiscoveryEndpoint(() => getPostHogProviderData({
  personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY!,
  projectId: process.env.POSTHOG_PROJECT_ID!,
}))
```

`getProviderData` calls PostHog's app host, which it derives from `POSTHOG_HOST`
(`https://us.i.posthog.com` becomes `https://us.posthog.com`, and the EU host maps
accordingly). Pass `appHost` explicitly if you use a self-hosted or proxied instance.
Missing credentials or host are reported back as hints in the Flags Explorer rather
than throwing.

<LearnMore icon="arrow" href="https://vercel.com/docs/flags/flags-explorer" target="_blank">
  Learn more about the Flags Explorer
</LearnMore>

## Additional resources

* [Cutting Costs](https://posthog.com/docs/feature-flags/cutting-costs)
* [Local Evaluation](https://posthog.com/docs/feature-flags/local-evaluation)


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)