@posthog/next 0.1.0

package/src/app/PostHogProvider.tsx

@@ -0,0 +1,141 @@
+import React from 'react'
+import type { PostHogConfig } from 'posthog-js'
+import { ClientPostHogProvider } from '../client/ClientPostHogProvider'
+import type { BootstrapConfig } from '../client/ClientPostHogProvider'
+import { cookies } from 'next/headers'
+import type { PostHogOptions } from 'posthog-node'
+import { getOrCreateNodeClient } from '../server/nodeClientCache'
+import { NEXTJS_CLIENT_DEFAULTS, resolveApiKey } from '../shared/config'
+import { readPostHogCookie, isOptedOut } from '../shared/cookie'
+
+type AllFlagsOptions = {
+    groups?: Record<string, string>
+    personProperties?: Record<string, string>
+    groupProperties?: Record<string, Record<string, string>>
+    onlyEvaluateLocally?: boolean
+    disableGeoip?: boolean
+    flagKeys?: string[]
+}
+
+export interface BootstrapFlagsConfig {
+    /** Specific flag keys to evaluate. If omitted, evaluates all flags. */
+    flags?: string[]
+    /** Groups to evaluate flags for (e.g., `{ company: 'posthog' }`). */
+    groups?: AllFlagsOptions['groups']
+    /** Known person properties to use for flag evaluation. */
+    personProperties?: AllFlagsOptions['personProperties']
+    /** Known group properties to use for flag evaluation, keyed by group type. */
+    groupProperties?: AllFlagsOptions['groupProperties']
+}
+
+export interface PostHogProviderProps {
+    /**
+     * PostHog project API key (starts with phc_).
+     * If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY` env var.
+     */
+    apiKey?: string
+    /** Optional posthog-js configuration overrides. */
+    clientOptions?: Partial<PostHogConfig>
+    /** Options passed to the posthog-node client used for server-side flag evaluation. */
+    serverOptions?: Partial<PostHogOptions>
+    /**
+     * Enable server-side feature flag evaluation for bootstrap.
+     *
+     * When enabled, the provider calls `cookies()` to read the user's
+     * identity and evaluates flags via `posthog-node`. This opts the
+     * route into **dynamic rendering** (incompatible with static
+     * generation / ISR).
+     *
+     * When omitted or falsy (default), no dynamic APIs are called and
+     * the provider is safe for static rendering and PPR.
+     */
+    bootstrapFlags?: boolean | BootstrapFlagsConfig
+    children: React.ReactNode
+}
+
+/**
+ * PostHog provider for Next.js App Router.
+ *
+ * By default this component is **static-safe** — it does not call any
+ * dynamic APIs (`cookies()`, `headers()`) and is compatible with static
+ * generation, ISR, and Partial Prerendering (PPR).
+ *
+ * When `bootstrapFlags` is enabled, the provider evaluates feature flags
+ * on the server and bootstraps the client SDK, which opts the route into
+ * dynamic rendering.
+ *
+ * All PostHog hooks (`usePostHog`, `useFeatureFlagEnabled`, etc.)
+ * require this provider as an ancestor.
+ */
+export async function PostHogProvider({
+    apiKey: apiKeyProp,
+    clientOptions,
+    serverOptions,
+    bootstrapFlags,
+    children,
+}: PostHogProviderProps) {
+    const apiKey = resolveApiKey(apiKeyProp)
+    if (!apiKey.startsWith('phc_')) {
+        // eslint-disable-next-line no-console
+        console.warn(
+            `[PostHog Next.js] apiKey "${apiKey}" does not start with "phc_". This may not be a valid PostHog project API key.`
+        )
+    }
+
+    const host = clientOptions?.api_host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST
+    const resolvedOptions: Partial<PostHogConfig> = {
+        ...NEXTJS_CLIENT_DEFAULTS,
+        ...clientOptions,
+        ...(host ? { api_host: host } : {}),
+    }
+
+    let bootstrap: BootstrapConfig | undefined
+
+    if (bootstrapFlags) {
+        try {
+            bootstrap = await evaluateFlags(apiKey, resolvedOptions, bootstrapFlags, serverOptions)
+
+            // Only disable the first-load fetch when we actually have bootstrap data.
+            // If evaluateFlags returned undefined (no cookie, opted-out), the client
+            // still needs to fetch flags on first load.
+            if (bootstrap) {
+                resolvedOptions.advanced_disable_feature_flags_on_first_load = true
+            }
+        } catch (error) {
+            // eslint-disable-next-line no-console
+            console.warn('[PostHog Next.js] Failed to evaluate bootstrap flags:', error)
+        }
+    }
+
+    return (
+        <ClientPostHogProvider apiKey={apiKey} options={resolvedOptions} bootstrap={bootstrap}>
+            {children}
+        </ClientPostHogProvider>
+    )
+}
+
+async function evaluateFlags(
+    apiKey: string,
+    options: Partial<PostHogConfig> | undefined,
+    bootstrapFlags: boolean | BootstrapFlagsConfig,
+    serverOptions?: Partial<PostHogOptions>
+): Promise<BootstrapConfig | undefined> {
+    const cookieStore = await cookies()
+
+    if (isOptedOut(cookieStore, apiKey, options)) {
+        return undefined
+    }
+
+    const cookieState = readPostHogCookie(cookieStore, apiKey)
+    if (!cookieState) {
+        return undefined
+    }
+
+    const host = serverOptions?.host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST
+    const nodeOptions: Partial<PostHogOptions> = { ...serverOptions, ...(host ? { host } : {}) }
+    const client = await getOrCreateNodeClient(apiKey, nodeOptions)
+
+    const { flags: flagKeys, ...flagOptions } = typeof bootstrapFlags === 'object' ? bootstrapFlags : {}
+    const allFlagsOptions: AllFlagsOptions = { ...flagOptions, ...(flagKeys ? { flagKeys } : {}) }
+    return client.getAllFlagsAndPayloads(cookieState.distinctId, allFlagsOptions)
+}

package/src/client/ClientPostHogProvider.tsx

@@ -0,0 +1,51 @@
+'use client'
+
+import React from 'react'
+import posthogJs from 'posthog-js'
+import { PostHogProvider as ReactPostHogProvider } from 'posthog-js/react'
+import type { BootstrapConfig, PostHogConfig } from 'posthog-js'
+
+export type { BootstrapConfig }
+
+export interface ClientPostHogProviderProps {
+    /** PostHog project API key (starts with phc_) */
+    apiKey: string
+    /** Optional posthog-js configuration overrides */
+    options?: Partial<PostHogConfig>
+    /** Server-evaluated feature flag values to bootstrap the client SDK with */
+    bootstrap?: BootstrapConfig
+    children: React.ReactNode
+}
+
+/**
+ * Client-side PostHog provider with SSR bootstrap support.
+ *
+ * This is an internal component rendered by PostHogProvider (server component).
+ * It forwards bootstrap data to posthog-js so flag hooks return real values
+ * immediately without a network round-trip.
+ *
+ * We initialize posthog-js eagerly during render (client-side only) rather than
+ * deferring to a useEffect. React fires effects bottom-up, so child useEffects
+ * (e.g. a consent banner) would access the posthog instance before the parent
+ * provider's useEffect calls init(). By initializing during render and passing
+ * the `client` prop, we guarantee the instance is fully configured before any
+ * child code runs.
+ */
+export function ClientPostHogProvider({ apiKey, options, bootstrap, children }: ClientPostHogProviderProps) {
+    if (!apiKey) {
+        // eslint-disable-next-line no-console
+        console.warn('[PostHog Next.js] apiKey is required — PostHog will not be initialized')
+        return <>{children}</>
+    }
+
+    const mergedOptions = bootstrap ? { ...options, bootstrap: { ...options?.bootstrap, ...bootstrap } } : options
+
+    // Initialize eagerly during render on the client so that child effects
+    // see a fully configured posthog instance. The `__loaded` guard prevents
+    // double-init (e.g. React StrictMode).
+    if (typeof window !== 'undefined' && !posthogJs.__loaded) {
+        posthogJs.init(apiKey, mergedOptions)
+    }
+
+    return <ReactPostHogProvider client={posthogJs}>{children}</ReactPostHogProvider>
+}

package/src/client/PostHogPageView.tsx

@@ -0,0 +1,63 @@
+'use client'
+
+import { Suspense, useEffect } from 'react'
+import { usePathname, useSearchParams } from 'next/navigation'
+import { usePostHog } from 'posthog-js/react'
+
+/**
+ * Tracks pageviews on route change in Next.js App Router.
+ *
+ * Place this component inside your `PostHogProvider` (typically in `app/layout.tsx`).
+ * It will automatically capture a `$pageview` event whenever the route changes.
+ *
+ * Includes its own Suspense boundary (required by `useSearchParams()`), so you
+ * don't need to wrap it in one yourself.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { PostHogProvider, PostHogPageView } from '@posthog/next'
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <PostHogProvider apiKey={process.env.NEXT_PUBLIC_POSTHOG_KEY!}>
+ *           <PostHogPageView />
+ *           {children}
+ *         </PostHogProvider>
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ */
+export function PostHogPageView() {
+    return (
+        <Suspense fallback={null}>
+            <PageViewTracker />
+        </Suspense>
+    )
+}
+
+function PageViewTracker() {
+    const pathname = usePathname()
+    const searchParams = useSearchParams()
+    const posthog = usePostHog()
+
+    useEffect(() => {
+        if (!posthog) {
+            return
+        }
+
+        let url = pathname
+        const search = searchParams.toString()
+        if (search) {
+            url = `${pathname}?${search}`
+        }
+
+        posthog.capture('$pageview', { $current_url: url })
+    }, [pathname, searchParams, posthog])
+
+    return null
+}

package/src/client/hooks.ts

@@ -0,0 +1,8 @@
+'use client'
+
+export {
+    usePostHog,
+    useFeatureFlagResult as useFeatureFlag,
+    useActiveFeatureFlags,
+    PostHogFeature,
+} from 'posthog-js/react'

package/src/index.client.ts

@@ -0,0 +1,9 @@
+// Browser-safe exports. PostHogProvider (a server component) is excluded
+// because it imports posthog-node which uses Node.js APIs.
+export { PostHogPageView } from './client/PostHogPageView'
+export { DEFAULT_INGEST_PATH } from './shared/constants'
+export { usePostHog, useFeatureFlag, useActiveFeatureFlags, PostHogFeature } from './client/hooks'
+
+// Re-export types (type-only, erased at build time)
+export type { PostHogProviderProps, BootstrapFlagsConfig } from './app/PostHogProvider'
+export type { PostHogMiddlewareOptions, PostHogProxyOptions } from './middleware/postHogMiddleware'

package/src/index.edge.ts

@@ -0,0 +1,10 @@
+// Edge-runtime exports (middleware). Excludes PostHogProvider and
+// posthog-node which require Node.js APIs.
+export { postHogMiddleware } from './middleware/postHogMiddleware'
+export { PostHogPageView } from './client/PostHogPageView'
+export { DEFAULT_INGEST_PATH } from './shared/constants'
+export { usePostHog, useFeatureFlag, useActiveFeatureFlags, PostHogFeature } from './client/hooks'
+
+// Re-export types (type-only, erased at build time)
+export type { PostHogProviderProps, BootstrapFlagsConfig } from './app/PostHogProvider'
+export type { PostHogMiddlewareOptions, PostHogProxyOptions } from './middleware/postHogMiddleware'

package/src/index.react-server.ts

@@ -0,0 +1,7 @@
+// Server component exports (only available in react-server context)
+export { PostHogProvider } from './app/PostHogProvider'
+export type { PostHogProviderProps, BootstrapFlagsConfig } from './app/PostHogProvider'
+
+// Client-safe exports (re-exported so server components can also import them)
+export { PostHogPageView } from './client/PostHogPageView'
+export { usePostHog, useFeatureFlag, useActiveFeatureFlags, PostHogFeature } from './client/hooks'

package/src/index.ts

@@ -0,0 +1,8 @@
+export { PostHogProvider } from './app/PostHogProvider'
+export { getPostHog } from './server/getPostHog'
+export { postHogMiddleware } from './middleware/postHogMiddleware'
+export { PostHogPageView } from './client/PostHogPageView'
+export { DEFAULT_INGEST_PATH } from './shared/constants'
+export { usePostHog, useFeatureFlag, useActiveFeatureFlags, PostHogFeature } from './client/hooks'
+export type { PostHogProviderProps, BootstrapFlagsConfig } from './app/PostHogProvider'
+export type { PostHogMiddlewareOptions, PostHogProxyOptions } from './middleware/postHogMiddleware'

package/src/middleware/postHogMiddleware.ts

@@ -0,0 +1,170 @@
+import 'server-only'
+
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { getPostHogCookieName, readPostHogCookie, serializePostHogCookie, isOptedOut } from '../shared/cookie'
+import { generateAnonymousId } from '../shared/identity'
+import { resolveApiKey } from '../shared/config'
+import { COOKIE_MAX_AGE_SECONDS, DEFAULT_API_HOST, DEFAULT_INGEST_PATH } from '../shared/constants'
+
+export interface PostHogProxyOptions {
+    /** Path prefix to intercept. Default: '/ingest'. */
+    pathPrefix?: string
+    /** PostHog ingest host to rewrite to. Default: 'https://us.i.posthog.com' */
+    host?: string
+}
+
+/**
+ * Configuration for the PostHog middleware.
+ */
+export interface PostHogMiddlewareOptions {
+    /**
+     * PostHog project API key (starts with phc_).
+     * If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY` env var.
+     */
+    apiKey?: string
+    /** Cookie max age in seconds. Default: 365 days. */
+    cookieMaxAgeSeconds?: number
+    /**
+     * An existing response to seed the PostHog cookie on.
+     *
+     * When provided, the middleware seeds the identity cookie on this response
+     * instead of creating a new one via `NextResponse.next()`. This enables
+     * composition with other middleware.
+     *
+     * @example
+     * ```ts
+     * export default async function middleware(request: NextRequest) {
+     *     const response = NextResponse.next()
+     *     response.headers.set('x-custom', 'value')
+     *     return postHogMiddleware({ response })(request)
+     * }
+     * ```
+     */
+    response?: NextResponse
+    /**
+     * When true, skips cookie seeding when no consent cookie is present.
+     * Mirrors the client-side `opt_out_capturing_by_default` option.
+     */
+    optOutByDefault?: boolean
+    /**
+     * Custom name for the consent cookie.
+     * Mirrors the client-side `consent_persistence_name` option.
+     */
+    consentCookieName?: string
+    /**
+     * Custom prefix for the consent cookie (appended with apiKey).
+     * Mirrors the client-side `opt_out_capturing_cookie_prefix` option.
+     */
+    consentCookiePrefix?: string
+    /**
+     * Proxy PostHog API requests through your app's domain.
+     *
+     * When enabled, requests matching the path prefix (default: `/ingest`)
+     * are rewritten to the PostHog ingest host, allowing SDK traffic to
+     * flow through your app's domain.
+     *
+     * Set to `true` for defaults, or pass an object to customize the path
+     * prefix and/or target host.
+     *
+     * When using the proxy, set `api_host` to the path prefix (e.g. `/ingest`)
+     * in your PostHogProvider options so the client SDK sends requests to
+     * your app's domain.
+     */
+    proxy?: boolean | PostHogProxyOptions
+}
+
+interface ResolvedRewriteConfig {
+    pathPrefix: string
+    host: string
+}
+
+function resolveProxyConfig(proxy: boolean | PostHogProxyOptions | undefined): ResolvedRewriteConfig | null {
+    if (!proxy) {
+        return null
+    }
+    const options = typeof proxy === 'object' ? proxy : {}
+    const prefix = options.pathPrefix ?? DEFAULT_INGEST_PATH
+    return {
+        pathPrefix: prefix.startsWith('/') ? prefix : `/${prefix}`,
+        host: options.host ?? DEFAULT_API_HOST,
+    }
+}
+
+function rewriteToPostHog(request: NextRequest, config: ResolvedRewriteConfig): NextResponse {
+    const pathname = request.nextUrl.pathname.slice(config.pathPrefix.length) || '/'
+    // eslint-disable-next-line compat/compat
+    const url = new URL(pathname, config.host)
+    url.search = request.nextUrl.search
+    return NextResponse.rewrite(url)
+}
+
+/**
+ * Creates a Next.js middleware that seeds the PostHog identity cookie
+ * on first visit and optionally rewrites API requests to PostHog's
+ * ingest host.
+ *
+ * @example Standalone (simplest — reads apiKey from NEXT_PUBLIC_POSTHOG_KEY)
+ * ```ts
+ * // middleware.ts
+ * import { postHogMiddleware } from '@posthog/next'
+ *
+ * export default postHogMiddleware({ proxy: true })
+ *
+ * export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] }
+ * ```
+ *
+ * @example Composed with other middleware
+ * ```ts
+ * import { postHogMiddleware } from '@posthog/next'
+ *
+ * export default async function middleware(request: NextRequest) {
+ *   const response = otherMiddleware(request)
+ *   return postHogMiddleware({ proxy: true, response })(request)
+ * }
+ * ```
+ */
+export function postHogMiddleware(config: PostHogMiddlewareOptions = {}) {
+    const apiKey = resolveApiKey(config.apiKey)
+    const proxyConfig = resolveProxyConfig(config.proxy)
+
+    return async function middleware(request: NextRequest) {
+        // Proxy ingest requests to PostHog's host. These are API calls
+        // from the browser SDK and don't need cookie seeding.
+        if (proxyConfig && request.nextUrl.pathname.startsWith(proxyConfig.pathPrefix)) {
+            return rewriteToPostHog(request, proxyConfig)
+        }
+
+        const cookieName = getPostHogCookieName(apiKey)
+        const state = readPostHogCookie(request.cookies, apiKey)
+        const response = config.response ?? NextResponse.next()
+
+        const optedOut = isOptedOut(request.cookies, apiKey, {
+            opt_out_capturing_by_default: config.optOutByDefault,
+            consent_persistence_name: config.consentCookieName,
+            opt_out_capturing_cookie_prefix: config.consentCookiePrefix,
+        })
+
+        if (optedOut) {
+            if (state) {
+                response.cookies.delete(cookieName)
+            }
+            return response
+        }
+
+        // Seed the PostHog cookie on first visit so server and client
+        // share the same identity from the first render.
+        if (!state) {
+            const distinctId = generateAnonymousId()
+            response.cookies.set(cookieName, serializePostHogCookie(distinctId), {
+                path: '/',
+                sameSite: 'lax',
+                secure: request.nextUrl.protocol === 'https:',
+                maxAge: config.cookieMaxAgeSeconds ?? COOKIE_MAX_AGE_SECONDS,
+                httpOnly: false,
+            })
+        }
+
+        return response
+    }
+}

package/src/pages/PostHogPageView.tsx

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+import { useRouter } from 'next/router'
+import { usePostHog } from 'posthog-js/react'
+
+/**
+ * Tracks pageviews on route change in Next.js Pages Router.
+ *
+ * Place this component inside your `PostHogProvider` in `pages/_app.tsx`.
+ * It will automatically capture a `$pageview` event whenever the route changes.
+ *
+ * Uses `router.asPath` which includes query parameters and hash fragments.
+ *
+ * @example
+ * ```tsx
+ * // pages/_app.tsx
+ * import { PostHogProvider, PostHogPageView } from '@posthog/next/pages'
+ *
+ * export default function App({ Component, pageProps }: AppProps) {
+ *   return (
+ *     <PostHogProvider apiKey={process.env.NEXT_PUBLIC_POSTHOG_KEY!}>
+ *       <PostHogPageView />
+ *       <Component {...pageProps} />
+ *     </PostHogProvider>
+ *   )
+ * }
+ * ```
+ */
+export function PostHogPageView() {
+    const router = useRouter()
+    const posthog = usePostHog()
+
+    useEffect(() => {
+        if (!posthog || !router.isReady) {
+            return
+        }
+
+        posthog.capture('$pageview', { $current_url: router.asPath })
+    }, [router.asPath, router.isReady, posthog])
+
+    return null
+}

package/src/pages/PostHogProvider.tsx

@@ -0,0 +1,61 @@
+import React from 'react'
+import type { PostHogConfig, BootstrapConfig } from 'posthog-js'
+import { ClientPostHogProvider } from '../client/ClientPostHogProvider'
+import { NEXTJS_CLIENT_DEFAULTS, resolveApiKey } from '../shared/config'
+
+export interface PagesPostHogProviderProps {
+    /**
+     * PostHog project API key (starts with phc_).
+     * If omitted, reads from `NEXT_PUBLIC_POSTHOG_KEY` env var.
+     */
+    apiKey?: string
+    /** Optional posthog-js configuration overrides. */
+    clientOptions?: Partial<PostHogConfig>
+    /** Server-evaluated bootstrap data from getServerSidePostHog. */
+    bootstrap?: BootstrapConfig
+    children: React.ReactNode
+}
+
+/**
+ * PostHog provider for Next.js Pages Router.
+ *
+ * Place this in your `pages/_app.tsx` wrapping `<Component {...pageProps} />`.
+ *
+ * @example
+ * ```tsx
+ * import { PostHogProvider } from '@posthog/next/pages'
+ *
+ * export default function App({ Component, pageProps }: AppProps) {
+ *   return (
+ *     <PostHogProvider apiKey={process.env.NEXT_PUBLIC_POSTHOG_KEY!}>
+ *       <Component {...pageProps} />
+ *     </PostHogProvider>
+ *   )
+ * }
+ * ```
+ */
+let apiKeyWarned = false
+
+export function PostHogProvider({ apiKey: apiKeyProp, clientOptions, bootstrap, children }: PagesPostHogProviderProps) {
+    const apiKey = resolveApiKey(apiKeyProp)
+    if (!apiKeyWarned && !apiKey.startsWith('phc_')) {
+        apiKeyWarned = true
+        // eslint-disable-next-line no-console
+        console.warn(
+            `[PostHog Next.js] apiKey "${apiKey}" does not start with "phc_". This may not be a valid PostHog project API key.`
+        )
+    }
+
+    const host = clientOptions?.api_host ?? process.env.NEXT_PUBLIC_POSTHOG_HOST
+    const resolvedOptions: Partial<PostHogConfig> = {
+        ...NEXTJS_CLIENT_DEFAULTS,
+        ...clientOptions,
+        ...(host ? { api_host: host } : {}),
+    }
+
+    return (
+        <ClientPostHogProvider apiKey={apiKey} options={resolvedOptions} bootstrap={bootstrap}>
+            {children}
+        </ClientPostHogProvider>
+    )
+}

package/src/pages/getServerSidePostHog.ts

@@ -0,0 +1,49 @@
+import type { GetServerSidePropsContext } from 'next'
+import type { PostHogOptions, IPostHog } from 'posthog-node'
+import { getOrCreateNodeClient } from '../server/nodeClientCache'
+import { cookieStoreFromHeader, readPostHogCookie, cookieStateToProperties, isOptedOut } from '../shared/cookie'
+import { resolveApiKey } from '../shared/config'
+
+/**
+ * Creates a PostHog server client scoped to the current request.
+ *
+ * Reads the user's identity from the PostHog cookie in request headers
+ * and sets it as context via `enterContext()`. The returned client is
+ * ready to use — methods like `getAllFlags()`, `getFeatureFlagResult()`,
+ * and `capture()` automatically use the current user's identity.
+ *
+ * @param ctx - The Next.js GetServerSidePropsContext
+ * @param apiKey - PostHog project API key. If omitted, reads from NEXT_PUBLIC_POSTHOG_KEY.
+ * @param options - Optional posthog-node configuration
+ *
+ * @example
+ * ```tsx
+ * import { getServerSidePostHog } from '@posthog/next/pages'
+ *
+ * export const getServerSideProps: GetServerSideProps = async (ctx) => {
+ *   const posthog = await getServerSidePostHog(ctx)
+ *   const flags = await posthog.getAllFlagsAndPayloads()
+ *   return { props: { posthogBootstrap: flags } }
+ * }
+ * ```
+ */
+export async function getServerSidePostHog(
+    ctx: GetServerSidePropsContext,
+    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 = cookieStoreFromHeader(ctx.req.headers.cookie || '')
+
+    if (!isOptedOut(cookieStore, resolvedApiKey)) {
+        const state = readPostHogCookie(cookieStore, resolvedApiKey)
+        const properties = cookieStateToProperties(state)
+        client.enterContext({ distinctId: state?.distinctId, sessionId: state?.sessionId, properties })
+    }
+
+    return client
+}

package/src/pages.ts

@@ -0,0 +1,8 @@
+export { PostHogProvider } from './pages/PostHogProvider'
+export { getServerSidePostHog } from './pages/getServerSidePostHog'
+export { getPostHog } from './server/getPostHog'
+export { postHogMiddleware } from './middleware/postHogMiddleware'
+export { PostHogPageView } from './pages/PostHogPageView'
+export { DEFAULT_INGEST_PATH } from './shared/constants'
+export type { PagesPostHogProviderProps } from './pages/PostHogProvider'
+export type { PostHogMiddlewareOptions, PostHogProxyOptions } from './middleware/postHogMiddleware'