@posthog/next 0.1.0

package/src/server/getPostHog.ts

@@ -0,0 +1,66 @@
+import 'server-only'
+
+import { isFunction } from '@posthog/core'
+import type { PostHogOptions, IPostHog } from 'posthog-node'
+import { cookies } from 'next/headers'
+import { getOrCreateNodeClient } from './nodeClientCache'
+import { readPostHogCookie, cookieStateToProperties, isOptedOut } from '../shared/cookie'
+import { resolveApiKey } from '../shared/config'
+
+/**
+ * Returns a PostHog server client scoped to the current request.
+ *
+ * Reads the user's identity from the PostHog cookie and returns a
+ * request-scoped client. Methods like `getAllFlags()`, `getFeatureFlagResult()`,
+ * and `capture()` automatically use the current user's identity.
+ *
+ * Calls `cookies()` internally, which opts the route into dynamic rendering.
+ *
+ * @param apiKey - PostHog project API key. If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY`.
+ * @param options - Optional `posthog-node` configuration (e.g., `{ host: '...' }`).
+ * @returns A `posthog-node` client scoped to the current user.
+ *
+ * @example
+ * ```ts
+ * import { getPostHog } from '@posthog/next'
+ *
+ * export default async function Page() {
+ *     const posthog = await getPostHog()
+ *     const flags = await posthog.getAllFlags()
+ *     posthog.capture({ event: 'page_viewed' })
+ *     return <div>...</div>
+ * }
+ * ```
+ */
+export async function getPostHog(apiKey?: string, options?: Partial<PostHogOptions>): Promise<IPostHog> {
+    const resolvedApiKey = resolveApiKey(apiKey)
+    const host = options?.host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST
+    const resolvedOptions = host ? { ...options, host } : options
+    const client = await getOrCreateNodeClient(resolvedApiKey, resolvedOptions)
+    const cookieStore = await cookies()
+
+    if (isOptedOut(cookieStore, resolvedApiKey)) {
+        return client
+    }
+
+    const state = readPostHogCookie(cookieStore, resolvedApiKey)
+    const properties = cookieStateToProperties(state)
+    const contextData = { distinctId: state?.distinctId, sessionId: state?.sessionId, properties }
+
+    // Wrap the shared client in a Proxy that applies request-scoped context
+    // to every method call. We can't use enterContext() here because
+    // AsyncLocalStorage.enterWith() doesn't propagate back to the caller
+    // across the await boundary of this async function.
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'withContext') {
+                return Reflect.get(target, prop, receiver)
+            }
+            const value = Reflect.get(target, prop, receiver)
+            if (isFunction(value)) {
+                return (...args: unknown[]) => target.withContext(contextData, () => value.apply(target, args))
+            }
+            return value
+        },
+    }) as IPostHog
+}

package/src/server/nodeClientCache.ts

@@ -0,0 +1,37 @@
+import { PostHog } from 'posthog-node'
+import type { PostHogOptions } from 'posthog-node'
+
+const cache = new Map<string, PostHog>()
+
+// Auto-detect waitUntil from @vercel/functions at module load.
+// Fails gracefully in environments where it's not available.
+const autoDetectedWaitUntil: Promise<((p: Promise<unknown>) => void) | undefined> = import(
+    /* webpackIgnore: true */ '@vercel/functions'
+)
+    .then((mod) => mod.waitUntil)
+    .catch(() => undefined)
+
+/**
+ * Returns a cached PostHog node client, creating one if needed.
+ *
+ * Clients are cached by project key + host. Only the options from the first
+ * call for a given key+host pair take effect; subsequent calls with different
+ * options (e.g. flushAt, flushInterval) will return the existing client.
+ *
+ * On first call, awaits auto-detection of @vercel/functions waitUntil
+ * and merges it into options. Explicit options.waitUntil takes priority.
+ */
+export async function getOrCreateNodeClient(apiKey: string, options?: Partial<PostHogOptions>): Promise<PostHog> {
+    const key = `${apiKey}:${options?.host ?? ''}`
+    let client = cache.get(key)
+    if (!client) {
+        const waitUntil = options?.waitUntil ?? (await autoDetectedWaitUntil)
+        const mergedOptions: Partial<PostHogOptions> = {
+            ...(waitUntil ? { waitUntil } : {}),
+            ...options,
+        }
+        client = new PostHog(apiKey, mergedOptions)
+        cache.set(key, client)
+    }
+    return client
+}

package/src/shared/config.ts

@@ -0,0 +1,52 @@
+import type { PostHogConfig } from 'posthog-js'
+import type { PostHogOptions } from 'posthog-node'
+
+/**
+ * Configuration for the client-side PostHog provider.
+ * Extends the standard posthog-js config.
+ */
+export type PostHogClientConfig = Partial<PostHogConfig>
+
+/**
+ * Configuration for the server-side PostHog client.
+ * Extends the standard posthog-node options.
+ */
+export type PostHogServerConfig = PostHogOptions
+
+/**
+ * Resolves the PostHog API key from an explicit value or the
+ * `NEXT_PUBLIC_POSTHOG_KEY` environment variable.
+ *
+ * Throws if neither is available.
+ */
+export function resolveApiKey(apiKey?: string): string {
+    const resolved = apiKey || process.env.NEXT_PUBLIC_POSTHOG_KEY
+    if (!resolved) {
+        throw new Error(
+            '[PostHog Next.js] apiKey is required. Either pass it explicitly or set the NEXT_PUBLIC_POSTHOG_KEY environment variable.'
+        )
+    }
+    return resolved
+}
+
+/**
+ * Next.js-specific defaults for the posthog-js client.
+ *
+ * These ensure the server can read both identity and consent state from cookies:
+ * - `capture_pageview: false` — disables posthog-js automatic pageviews so the
+ *   `PostHogPageView` component can handle them without duplicates
+ * - `persistence: 'localStorage+cookie'` — already the posthog-js default, made explicit
+ * - `opt_out_capturing_persistence_type: 'cookie'` — writes consent state to a cookie
+ *   so middleware/server components can read it (posthog-js default is 'localStorage')
+ * - `opt_out_persistence_by_default: true` — when opted out, disables persistence
+ *   so posthog-js does not write cookies or localStorage; the middleware
+ *   handles deleting the identity cookie separately
+ *
+ * Users can override any of these via the `options` prop on PostHogProvider.
+ */
+export const NEXTJS_CLIENT_DEFAULTS: Partial<PostHogConfig> = {
+    capture_pageview: false,
+    persistence: 'localStorage+cookie',
+    opt_out_capturing_persistence_type: 'cookie',
+    opt_out_persistence_by_default: true,
+}

package/src/shared/constants.ts

@@ -0,0 +1,5 @@
+export const COOKIE_PREFIX = 'ph_'
+export const COOKIE_SUFFIX = '_posthog'
+export const DEFAULT_API_HOST = 'https://us.i.posthog.com'
+export const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60
+export const DEFAULT_INGEST_PATH = '/ingest'

package/src/shared/cookie.ts

@@ -0,0 +1,162 @@
+import { uuidv7, isNoLike, isArray } from '@posthog/core'
+import { COOKIE_PREFIX, COOKIE_SUFFIX } from './constants'
+
+/**
+ * Minimal cookie-reading interface compatible with Next.js `cookies()`,
+ * `request.cookies`, and plain objects.
+ */
+export interface CookieStore {
+    get(name: string): { value: string } | undefined
+}
+
+/**
+ * Adapts a raw `Cookie` header string into a {@link CookieStore}.
+ */
+export function cookieStoreFromHeader(cookieHeader: string): CookieStore {
+    const cookies: Record<string, string> = {}
+    if (cookieHeader) {
+        for (const pair of cookieHeader.split(';')) {
+            const [key, ...valueParts] = pair.trim().split('=')
+            if (key) {
+                cookies[key.trim()] = decodeURIComponent(valueParts.join('=').trim())
+            }
+        }
+    }
+    return { get: (name: string) => (name in cookies ? { value: cookies[name] } : undefined) }
+}
+
+export interface PostHogCookieState {
+    distinctId: string
+    isIdentified: boolean
+    sessionId?: string
+    deviceId?: string
+}
+
+/**
+ * Returns the PostHog cookie name for the given API key.
+ *
+ * PostHog-js stores state in a cookie named `ph_<sanitized_token>_posthog`.
+ * The token is sanitized by replacing `+` with `PL`, `/` with `SL`, `=` with `EQ`.
+ *
+ * @param apiKey - The PostHog project API key
+ * @returns The cookie name string
+ */
+export function getPostHogCookieName(apiKey: string): string {
+    const sanitized = apiKey.replace(/\+/g, 'PL').replace(/\//g, 'SL').replace(/=/g, 'EQ')
+    return `${COOKIE_PREFIX}${sanitized}${COOKIE_SUFFIX}`
+}
+
+/**
+ * Serializes an anonymous ID into the JSON format posthog-js expects.
+ *
+ * When `distinct_id === $device_id`, posthog-js treats the user as anonymous.
+ *
+ * @param anonymousId - The anonymous distinct ID to serialize
+ * @returns JSON string suitable for the PostHog cookie value
+ */
+export function serializePostHogCookie(anonymousId: string): string {
+    const now = Date.now()
+    const sessionId = uuidv7()
+    return JSON.stringify({
+        distinct_id: anonymousId,
+        $device_id: anonymousId,
+        $user_state: 'anonymous',
+        $sesid: [now, sessionId, now],
+    })
+}
+
+/**
+ * Reads and parses the PostHog cookie from a cookie store.
+ *
+ * Compatible with Next.js `cookies()`, `request.cookies`, and any object
+ * with a `get(name)` method that returns `{ value: string } | undefined`.
+ */
+export function readPostHogCookie(cookies: CookieStore, apiKey: string): PostHogCookieState | null {
+    const cookieName = getPostHogCookieName(apiKey)
+    const cookie = cookies.get(cookieName)
+    return cookie ? parsePostHogCookie(cookie.value) : null
+}
+
+/**
+ * Converts cookie state into PostHog properties (e.g. `$session_id`, `$device_id`).
+ */
+export function cookieStateToProperties(state: PostHogCookieState | null): Record<string, string> | undefined {
+    if (!state) {
+        return undefined
+    }
+    const props: Record<string, string> = {}
+    if (state.sessionId) {
+        props.$session_id = state.sessionId
+    }
+    if (state.deviceId) {
+        props.$device_id = state.deviceId
+    }
+    return Object.keys(props).length > 0 ? props : undefined
+}
+
+/**
+ * Parses a PostHog cookie value and extracts identity information.
+ *
+ * The cookie value is a JSON object containing `distinct_id` and `$user_state`.
+ * A user is considered identified if `$user_state` is `'identified'`.
+ *
+ * @param cookieValue - The raw cookie string value
+ * @returns Parsed identity state, or null if the cookie is missing/invalid
+ */
+export function parsePostHogCookie(cookieValue: string): PostHogCookieState | null {
+    if (!cookieValue) {
+        return null
+    }
+
+    try {
+        const parsed = JSON.parse(cookieValue)
+        if (!parsed || typeof parsed !== 'object' || !parsed.distinct_id) {
+            return null
+        }
+
+        // $sesid is stored as [lastActivityTimestamp, sessionId, sessionStartTimestamp]
+        const sesid = isArray(parsed.$sesid) ? parsed.$sesid[1] : undefined
+
+        return {
+            distinctId: String(parsed.distinct_id),
+            isIdentified: parsed.$user_state === 'identified',
+            sessionId: typeof sesid === 'string' ? sesid : undefined,
+            deviceId: typeof parsed.$device_id === 'string' ? parsed.$device_id : undefined,
+        }
+    } catch {
+        return null
+    }
+}
+
+export interface ConsentCookieConfig {
+    consent_persistence_name?: string | null
+    opt_out_capturing_cookie_prefix?: string | null
+}
+
+const CONSENT_PREFIX = '__ph_opt_in_out_'
+
+export function getConsentCookieName(apiKey: string, config?: ConsentCookieConfig): string {
+    if (config?.consent_persistence_name) {
+        return config.consent_persistence_name
+    }
+    if (config?.opt_out_capturing_cookie_prefix) {
+        return config.opt_out_capturing_cookie_prefix + apiKey
+    }
+    return CONSENT_PREFIX + apiKey
+}
+
+export interface ConsentConfig extends ConsentCookieConfig {
+    opt_out_capturing_by_default?: boolean
+}
+
+export function isOptedOut(cookies: CookieStore, apiKey: string, config?: ConsentConfig): boolean {
+    const cookieName = getConsentCookieName(apiKey, config)
+    const cookie = cookies.get(cookieName)
+
+    if (cookie) {
+        return isNoLike(cookie.value)
+    }
+
+    // No consent cookie means pending — defer to config
+    return config?.opt_out_capturing_by_default ?? false
+}

package/src/shared/identity.ts

@@ -0,0 +1,9 @@
+import { uuidv7 } from '@posthog/core'
+
+/**
+ * Generates a random anonymous distinct_id using UUIDv7.
+ * Used as a fallback when no PostHog cookie is available.
+ */
+export function generateAnonymousId(): string {
+    return uuidv7()
+}