Remix

PostHog makes it easy to get data about traffic and usage of your Remix app. Integrating PostHog into your site enables analytics about user behavior, custom events capture, session recordings, feature flags, and more.

This guide walks you through integrating PostHog into your Remix app using the JavaScript Web SDK.

Installation

Install posthog-js and @posthog/react:

npm install --save posthog-js @posthog/react

Start by setting posthog-js and @posthog/react as external packages in your vite.config.ts file.

If your site sets a Content-Security-Policy, it needs to allow PostHog. This applies to the snippet and to package installs alike: the SDK lazy-loads extra bundles (session replay, surveys) from PostHog's CDN, and sends events to the ingestion host. PostHog serves from subdomains of posthog.com that change over time, so allow the wildcard:

PostHog AI

script-src 'self' https://*.posthog.com;
connect-src 'self' https://*.posthog.com;
worker-src 'self' blob: data:;

script-src covers the snippet and the lazy-loaded bundles, connect-src covers event ingestion and feature flags, and worker-src covers session replay. The toolbar needs a few more, or use a reverse proxy so everything is first-party. Failing to do so causes silent failures where capture and identify calls never send, so the integration looks complete while zero events arrive. Remember connect-src falls back to default-src, so default-src 'self' blocks event delivery even when the script itself is bundled.

// vite.config.ts
// ... imports and rest of config

export default defineConfig({
  plugins: [
    remix({
      future: {
        v3_fetcherPersist: true,
        v3_relativeSplatPath: true,
        v3_throwAbortReason: true,
        v3_singleFetch: true,
        v3_lazyRouteDiscovery: true,
      },
    }),
    tsconfigPaths(),
  ],
  ssr: {
    noExternal: ["posthog-js", "@posthog/react"],
  },
});

Next, create a provider.tsx file in the app folder. In it, set up the PostHog provider to initialize after hydration. You'll need both your API key and instance address (you can find these in your project settings).

// app/provider.tsx
import { useEffect, useState } from "react";
import posthog from "posthog-js";
import { PostHogProvider } from "@posthog/react";

export function PHProvider({ children }: { children: React.ReactNode }) {
  const [hydrated, setHydrated] = useState(false);

  useEffect(() => {
    posthog.init("<ph_project_token>", {
      api_host: "https://us.i.posthog.com",
      defaults: "2026-05-30",
    });

    setHydrated(true);
  }, []);

  if (!hydrated) return <>{children}</>;
  return <PostHogProvider client={posthog}>{children}</PostHogProvider>;
}

Finally, import the PHProvider component in your app/root.tsx file and use it to wrap your app.

// app/root.tsx
// ... imports
import { PHProvider } from "./provider";

// ... links, meta, etc.

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <PHProvider>
          {children}
          <ScrollRestoration />
          <Scripts />
        </PHProvider>
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

When you run your app now, PostHog will automatically capture events and pageviews. You can also use the other features of PostHog by importing and using the usePostHog hook in your components.

Node.js server context and traces

For a Remix server on Node.js, use the @remix-run/express adapter and the shared Node SDK request middleware. The browser setup above does not add server context.

Reuse one posthog-node client from your server setup. Add PostHogContextSpanProcessor from posthog-node/otel to your application's existing OpenTelemetry provider. Keep your exporter, sampler, and other processors. Load your tracing setup, including HTTP and Express instrumentation, before importing the server modules below.

import express from 'express'
import { createRequestHandler } from '@remix-run/express'
import { setupExpressRequestContext } from 'posthog-node'
import posthog from './posthog.server.js'
import * as build from './build/server/index.js'

const app = express()

setupExpressRequestContext(posthog, app)

app.all('*', createRequestHandler({
    build,
    getLoadContext: () => ({ posthog }),
}))

Place the middleware before createRequestHandler. This covers document requests, loader data requests, actions, resource routes, server rendering, and streamed responses. Wrapping only entry.server misses loader and action requests that do not render a document.

The middleware reads the PostHog tracing headers and fills missing context. An existing application identity takes precedence over the browser value. Use your existing authentication setup for application identity. These headers are analytics context and must not be used for authentication or authorization.

Only requests that carry the headers receive browser context. Fetch/XHR instrumentation does not add these headers to standard browser document navigations, so initial server rendering can have no browser IDs.

The optional processor adds sessionId and posthogDistinctId to application spans. At request entry, it can also fill missing IDs on the nearest recording HTTP server span through parent objects observed by the processor. Explicit canonical attributes keep their values. If the sampler drops an intermediate span, the processor cannot verify the earlier server ancestor and leaves it unchanged. Recording spans created within the request still receive context.

Request context stays active until the Express response finishes or closes. Async work that produces the response, including streaming work, can use it. New spans from detached work after that point have no request IDs. Use a new explicit context for a background job that needs its own IDs.

Remix handles many loader and action errors inside its router, so an Express error handler alone does not capture all of them. To capture these errors, use Remix's handleError export in app/entry.server.tsx with the same server client:

import posthog from '../posthog.server.js'

export function handleError(error: unknown) {
    posthog.captureException(error)
}

This setup was checked with Remix 2.17.5 and its Node.js Express adapter. Other adapters and runtimes need their own context and lifetime setup. See the Node.js tracing guide for the shared processor setup and limits.

Identifying users

Identifying users is required. Call posthog.identify('your-user-id') after login to link events to a known user. This is what connects frontend event captures, session replays, LLM traces, and error tracking to the same person — and lets backend events link back too.

Use a stable ID from your auth system when possible, not an email or display name. Send those as person properties instead. If your app has no other stable key, email works as a fallback if they are unique. Never a shared literal like "anonymous" or "user", which pools many people onto one person and corrupts their data. When no ID is available at all, skip the identify and retain the anonymous distinct ID that's automatically assigned.

Call posthog.reset() on logout, so the next person to use the browser doesn't inherit the last one's identity.

See our guide on identifying users for how to set this up.

If your app calls your own backend, tracing_headers adds X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID to matching fetch and XMLHttpRequest requests. This lets server-side SDKs link backend events, errors, and LLM traces back to frontend sessions and replays. Use hostnames only, without protocols or paths.

posthog.init('<ph_project_token>', {
  api_host: 'https://us.i.posthog.com',
  // Optional: send PostHog session/user context to your backend
  tracing_headers: ['api.example.com'],
})

This works in local development too, but match on the hostname alone: use 'localhost', not 'localhost:3000'. Ports are never part of a hostname, so a value with one in it never matches anything. localhost and 127.0.0.1 are also different hostnames — use whichever your app actually calls.

Tracing headers help you attribute events across front and backend consistently. When this isn't available, use your server-side stable IDs to deduce the matching distinctId, and pass it in when capturing the event.

Next steps

For any technical questions for how to integrate specific PostHog features into Remix (such as analytics, feature flags, A/B testing, surveys, etc.), have a look at our JavaScript Web SDK docs and React docs.

Alternatively, the following tutorials can help you get started:

• How to set up Remix analytics, feature flags, and more
• How to set up A/B tests in Remix
• How to set up surveys in Remix