references/EXAMPLE.md
PostHog React Router v7 - Framework mode Example Project
Repository: https://github.com/PostHog/context-mill Path: basics/react-react-router-7-framework
README.md
PostHog React Router 7 Framework example
This is a React Router 7 Framework example demonstrating PostHog integration with product analytics, session replay, feature flags, and error tracking.
Features
- Product Analytics: Track user events and behaviors
- Session Replay: Record and replay user sessions
- Error Tracking: Capture and track errors
- User Authentication: Demo login system with PostHog user identification
- Server-side & Client-side Tracking: Examples of both tracking methods
- SSR Support: Server-side rendering with React Router 7 Framework
Getting Started
1. Install Dependencies
npm install
# or
pnpm install
2. Configure Environment Variables
Create a .env file in the root directory:
VITE_PUBLIC_POSTHOG_PROJECT_TOKEN=your_posthog_project_token
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
Get your PostHog project token from your PostHog project settings.
3. Run the Development Server
npm run dev
# or
pnpm dev
Open http://localhost:5173 with your browser to see the app.
Project Structure
app/
├── components/
│ └── Header.tsx # Navigation header with auth state
├── contexts/
│ └── AuthContext.tsx # Authentication context
├── lib/
│ ├── posthog-middleware.ts # Server-side PostHog middleware
│ └── db.ts # Database utilities
├── routes/
│ ├── home.tsx # Home/Login page
│ ├── burrito.tsx # Demo feature page with event tracking
│ ├── profile.tsx # User profile with error tracking demo
│ ├── api.auth.login.ts # Login API with server-side tracking
│ └── api.burrito.consider.ts # Burrito API with server-side tracking
├── entry.client.tsx # Client entry with PostHog initialization
├── entry.server.tsx # Server entry
└── root.tsx # Root route with error boundary
Key Integration Points
Client-side initialization (entry.client.tsx)
import posthog from 'posthog-js';
import { PostHogProvider } from '@posthog/react'
posthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN, {
api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
defaults: '2026-01-30',
__add_tracing_headers: [ window.location.host, 'localhost' ],
});
<PostHogProvider client={posthog}>
<HydratedRouter />
</PostHogProvider>
User identification (home.tsx)
The user is identified when the user logs in on the client-side.
posthog?.identify(username, {
username: username,
});
posthog?.capture('user_logged_in', {
username: username,
});
The session and distinct ID are automatically passed to the backend via the X-POSTHOG-SESSION-ID and X-POSTHOG-DISTINCT-ID headers because we set the __add_tracing_headers option in the PostHog initialization.
Important: do not identify users on the server-side.
Server-side middleware (posthog-middleware.ts)
The PostHog middleware creates a server-side PostHog client for each request and extracts session and user context from request headers:
export const posthogMiddleware: Route.MiddlewareFunction = async ({ request, context }, next) => {
const posthog = new PostHog(process.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
host: process.env.VITE_PUBLIC_POSTHOG_HOST!,
flushAt: 1,
flushInterval: 0,
});
const sessionId = request.headers.get('X-POSTHOG-SESSION-ID');
const distinctId = request.headers.get('X-POSTHOG-DISTINCT-ID');
context.posthog = posthog;
const response = await posthog.withContext(
{ sessionId: sessionId ?? undefined, distinctId: distinctId ?? undefined },
next
);
await posthog.shutdown().catch(() => {});
return response;
};
Key Points:
- Creates a new PostHog Node client for each request
- Extracts
sessionIdanddistinctIdfrom request headers (automatically set by the client-side SDK) - Sets the PostHog client on the request context for use in route handlers
- Uses
withContext()to associate server-side events with the correct session/user - Properly shuts down the client after each request
Event tracking (burrito.tsx)
posthog?.capture('burrito_considered', {
total_considerations: count,
username: username,
});
Error tracking (root.tsx, profile.tsx)
Errors are captured in two ways:
- Error boundary - The
ErrorBoundaryinroot.tsxautomatically captures unhandled React Router errors:
export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
const posthog = usePostHog();
posthog.captureException(error);
// ... error UI
}
- Manual error capture in components (profile.tsx):
posthog.captureException(err);
Server-side tracking (api.auth.login.ts, api.burrito.consider.ts)
Server-side events use the PostHog client from the request context (set by the middleware):
const posthog = (context as any).posthog as PostHog | undefined;
if (posthog) {
posthog.capture({ event: 'server_login' });
}
Key Points:
- The PostHog client is available via
context.posthog(set by the middleware) - Events are automatically associated with the correct user/session via the middleware's
withContext()call - The
distinctIdandsessionIdare extracted from request headers and used to maintain context between client and server
Learn More
.env.example
VITE_PUBLIC_POSTHOG_PROJECT_TOKEN=
VITE_PUBLIC_POSTHOG_HOST=
PROJECT_ID=
app/components/Header.tsx
import { Link } from 'react-router';
import { useAuth } from '../contexts/AuthContext';
import { usePostHog } from '@posthog/react';
export default function Header() {
const { user, logout } = useAuth();
const posthog = usePostHog();
const handleLogout = () => {
posthog?.capture('user_logged_out');
posthog?.reset();
logout();
};
return (
<header className="header">
<div className="header-container">
<nav>
<Link to="/">Home</Link>
{user && (
<>
<Link to="/burrito">Burrito Consideration</Link>
<Link to="/profile">Profile</Link>
<Link to="/error">Error</Link>
</>
)}
</nav>
<div className="user-section">
{user ? (
<>
<span>Welcome, {user.username}!</span>
<button onClick={handleLogout} className="btn-logout">
Logout
</button>
</>
) : (
<span>Not logged in</span>
)}
</div>
</div>
</header>
);
}
app/contexts/AuthContext.tsx
import { createContext, useContext, useState, type ReactNode } from 'react';
interface User {
username: string;
burritoConsiderations: number;
}
interface AuthContextType {
user: User | null;
login: (username: string, password: string) => Promise<boolean>;
logout: () => void;
incrementBurritoConsiderations: () => void;
setUser: (user: User) => void;
}
const AuthContext = createContext<AuthContextType | undefined>(undefined);
const users: Map<string, User> = new Map();
export function AuthProvider({ children }: { children: ReactNode }) {
const [user, setUser] = useState<User | null>(() => {
if (typeof window === 'undefined') return null;
const storedUsername = localStorage.getItem('currentUser');
if (storedUsername) {
const existingUser = users.get(storedUsername);
if (existingUser) {
return existingUser;
}
}
return null;
});
const login = async (username: string, password: string): Promise<boolean> => {
try {
const response = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username, password }),
});
if (response.ok) {
const { user: userData } = await response.json();
let localUser = users.get(username);
if (!localUser) {
localUser = userData as User;
users.set(username, localUser);
}
setUser(localUser);
localStorage.setItem('currentUser', username);
return true;
}
return false;
} catch (error) {
console.error('Login error:', error);
return false;
}
};
const logout = () => {
setUser(null);
localStorage.removeItem('currentUser');
};
const incrementBurritoConsiderations = () => {
if (user) {
user.burritoConsiderations++;
users.set(user.username, user);
setUser({ ...user });
}
};
const setUserState = (newUser: User) => {
setUser(newUser);
users.set(newUser.username, newUser);
};
return (
<AuthContext.Provider value={{ user, login, logout, incrementBurritoConsiderations, setUser: setUserState }}>
{children}
</AuthContext.Provider>
);
}
export function useAuth() {
const context = useContext(AuthContext);
if (context === undefined) {
throw new Error('useAuth must be used within an AuthProvider');
}
return context;
}
app/entry.client.tsx
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import posthog from 'posthog-js';
import { PostHogProvider } from '@posthog/react'
posthog.init(import.meta.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN, {
api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
defaults: '2026-01-30',
__add_tracing_headers: [ window.location.host, 'localhost' ],
});
startTransition(() => {
hydrateRoot(
document,
<PostHogProvider client={posthog}>
<StrictMode>
<HydratedRouter />
</StrictMode>
</PostHogProvider>,
);
});
app/entry.server.tsx
import { PassThrough } from "node:stream";
import type { EntryContext, RouterContextProvider } from "react-router";
import { createReadableStreamFromReadable } from "@react-router/node";
import { ServerRouter } from "react-router";
import { isbot } from "isbot";
import type { RenderToPipeableStreamOptions } from "react-dom/server";
import { renderToPipeableStream } from "react-dom/server";
export const streamTimeout = 5_000;
export default function handleRequest(
request: Request,
responseStatusCode: number,
responseHeaders: Headers,
routerContext: EntryContext,
loadContext: RouterContextProvider,
) {
// https://httpwg.org/specs/rfc9110.html#HEAD
if (request.method.toUpperCase() === "HEAD") {
return new Response(null, {
status: responseStatusCode,
headers: responseHeaders,
});
}
return new Promise((resolve, reject) => {
let shellRendered = false;
let userAgent = request.headers.get("user-agent");
// Ensure requests from bots and SPA Mode renders wait for all content to load before responding
// https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
let readyOption: keyof RenderToPipeableStreamOptions =
(userAgent && isbot(userAgent)) || routerContext.isSpaMode
? "onAllReady"
: "onShellReady";
// Abort the rendering stream after the `streamTimeout` so it has time to
// flush down the rejected boundaries
let timeoutId: ReturnType<typeof setTimeout> | undefined = setTimeout(
() => abort(),
streamTimeout + 1000,
);
const { pipe, abort } = renderToPipeableStream(
<ServerRouter context={routerContext} url={request.url} />,
{
[readyOption]() {
shellRendered = true;
const body = new PassThrough({
final(callback) {
// Clear the timeout to prevent retaining the closure and memory leak
clearTimeout(timeoutId);
timeoutId = undefined;
callback();
},
});
const stream = createReadableStreamFromReadable(body);
responseHeaders.set("Content-Type", "text/html");
pipe(body);
resolve(
new Response(stream, {
headers: responseHeaders,
status: responseStatusCode,
}),
);
},
onShellError(error: unknown) {
reject(error);
},
onError(error: unknown) {
responseStatusCode = 500;
// Log streaming rendering errors from inside the shell. Don't log
// errors encountered during initial shell rendering since they'll
// reject and get logged in handleDocumentRequest.
if (shellRendered) {
console.error(error);
}
},
},
);
});
}
app/lib/db.ts
import sqlite3 from "sqlite3";
import { join } from "node:path";
import { promisify } from "node:util";
const dbPath = join(process.cwd(), "burrito-considerations.db");
const db = new sqlite3.Database(dbPath);
// Initialize schema
db.serialize(() => {
db.run(`
CREATE TABLE IF NOT EXISTS burrito_considerations (
username TEXT PRIMARY KEY,
count INTEGER NOT NULL DEFAULT 0
)
`);
});
const dbGet = promisify(db.get.bind(db));
const dbRun = promisify(db.run.bind(db));
export function getBurritoConsiderations(username: string): Promise<number> {
return dbGet("SELECT count FROM burrito_considerations WHERE username = ?", [username])
.then((row: any) => row?.count ?? 0);
}
export function incrementBurritoConsiderations(username: string): Promise<number> {
return dbRun(`
INSERT INTO burrito_considerations (username, count)
VALUES (?, 1)
ON CONFLICT(username) DO UPDATE SET count = count + 1
`, [username])
.then(() => {
return dbGet("SELECT count FROM burrito_considerations WHERE username = ?", [username]);
})
.then((row: any) => row.count);
}
app/lib/posthog-middleware.ts
import { PostHog } from "posthog-node";
import type { RouterContextProvider } from "react-router";
import type { Route } from "../+types/root";
export interface PostHogContext extends RouterContextProvider {
posthog?: PostHog;
}
export const posthogMiddleware: Route.MiddlewareFunction = async ({ request, context }, next) => {
const posthog = new PostHog(process.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
host: process.env.VITE_PUBLIC_POSTHOG_HOST!,
flushAt: 1,
flushInterval: 0,
});
const sessionId = request.headers.get('X-POSTHOG-SESSION-ID');
const distinctId = request.headers.get('X-POSTHOG-DISTINCT-ID');
(context as PostHogContext).posthog = posthog;
const response = await posthog.withContext(
{ sessionId: sessionId ?? undefined, distinctId: distinctId ?? undefined },
next
);
await posthog.shutdown().catch(() => {});
return response;
};
app/root.tsx
import { usePostHog } from '@posthog/react';
import {
isRouteErrorResponse,
Links,
Meta,
Outlet,
Scripts,
ScrollRestoration,
} from "react-router";
import type { Route } from "./+types/root";
import "./app.css";
import "./globals.css";
import Header from "./components/Header";
import { AuthProvider } from "./contexts/AuthContext";
import { posthogMiddleware } from "./lib/posthog-middleware";
export const middleware: Route.MiddlewareFunction[] = [
posthogMiddleware,
];
export const links: Route.LinksFunction = () => [
{ rel: "preconnect", href: "https://fonts.googleapis.com" },
{
rel: "preconnect",
href: "https://fonts.gstatic.com",
crossOrigin: "anonymous",
},
{
rel: "stylesheet",
href: "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap",
},
];
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>
{children}
<ScrollRestoration />
<Scripts />
</body>
</html>
);
}
export default function App() {
return (
<AuthProvider>
<Header />
<main>
<Outlet />
</main>
</AuthProvider>
);
}
export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
let message = "Oops!";
let details = "An unexpected error occurred.";
let stack: string | undefined;
const posthog = usePostHog();
posthog.captureException(error);
if (isRouteErrorResponse(error)) {
message = error.status === 404 ? "404" : "Error";
details =
error.status === 404
? "The requested page could not be found."
: error.statusText || details;
} else if (import.meta.env.DEV && error && error instanceof Error) {
details = error.message;
stack = error.stack;
}
return (
<main className="pt-16 p-4 container mx-auto">
<h1>{message}</h1>
<p>{details}</p>
{stack && (
<pre className="w-full p-4 overflow-x-auto">
<code>{stack}</code>
</pre>
)}
</main>
);
}
app/routes.ts
import { type RouteConfig, index, route } from "@react-router/dev/routes";
export default [
index("routes/home.tsx"),
route("burrito", "routes/burrito.tsx"),
route("profile", "routes/profile.tsx"),
route("error", "routes/error.tsx"),
route("api/auth/login", "routes/api.auth.login.ts"),
route("api/burrito/consider", "routes/api.burrito.consider.ts"),
] satisfies RouteConfig;
app/routes/api.auth.login.ts
import type { Route } from "./+types/api.auth.login";
import { getBurritoConsiderations } from "../lib/db";
import type { PostHogContext } from "../lib/posthog-middleware";
const users = new Map<string, { username: string }>();
export { users };
export async function action({ request, context }: Route.ActionArgs) {
const body = await request.json();
const { username, password } = body;
if (!username || !password) {
return Response.json({ error: 'Username and password required' }, { status: 400 });
}
let user = users.get(username);
if (!user) {
user = { username };
users.set(username, user);
}
const posthog = (context as PostHogContext).posthog;
if (posthog) {
posthog.capture({ event: 'server_login' });
}
const burritoConsiderations = await getBurritoConsiderations(username);
return Response.json({
success: true,
user: { ...user, burritoConsiderations }
});
}
app/routes/api.burrito.consider.ts
import type { Route } from "./+types/api.burrito.consider";
import { users } from "./api.auth.login";
import { incrementBurritoConsiderations } from "../lib/db";
import type { PostHogContext } from "../lib/posthog-middleware";
export async function action({ request, context }: Route.ActionArgs) {
const body = await request.json();
const { username } = body;
if (!username) {
return Response.json({ error: 'Username required' }, { status: 400 });
}
const user = users.get(username);
if (!user) {
return Response.json({ error: 'User not found' }, { status: 404 });
}
const burritoConsiderations = await incrementBurritoConsiderations(username);
const posthog = (context as PostHogContext).posthog;
posthog?.capture({ event: 'burrito_considered' });
return Response.json({
success: true,
user: { ...user, burritoConsiderations }
});
}
app/routes/burrito.tsx
import { useState, useEffect } from 'react';
import { useNavigate } from 'react-router';
import type { Route } from "./+types/burrito";
import { useAuth } from '../contexts/AuthContext';
export function meta({}: Route.MetaArgs) {
return [
{ title: "Burrito Consideration - Burrito Consideration App" },
{ name: "description", content: "Consider the potential of burritos" },
];
}
export default function BurritoPage() {
const { user, setUser } = useAuth();
const navigate = useNavigate();
const [hasConsidered, setHasConsidered] = useState(false);
useEffect(() => {
if (!user) {
navigate('/');
}
}, [user, navigate]);
if (!user) {
return null;
}
const handleConsideration = async () => {
try {
const response = await fetch('/api/burrito/consider', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username: user.username }),
});
if (response.ok) {
const { user: updatedUser } = await response.json();
setUser(updatedUser);
setHasConsidered(true);
setTimeout(() => setHasConsidered(false), 2000);
} else {
console.error('Failed to increment burrito considerations');
}
} catch (err) {
console.error('Error considering burrito:', err);
}
};
return (
<div className="container">
<h1>Burrito consideration zone</h1>
<p>Take a moment to truly consider the potential of burritos.</p>
<div style={{ textAlign: 'center' }}>
<button
onClick={handleConsideration}
className="btn-burrito"
>
I have considered the burrito potential
</button>
{hasConsidered && (
<p className="success">
Thank you for your consideration! Count: {user.burritoConsiderations}
</p>
)}
</div>
<div className="stats">
<h3>Consideration stats</h3>
<p>Total considerations: {user.burritoConsiderations}</p>
</div>
</div>
);
}
app/routes/error.tsx
import type { Route } from "./+types/error";
export function meta({}: Route.MetaArgs) {
return [
{ title: "Error Test - Burrito Consideration App" },
{ name: "description", content: "Test error boundary" },
];
}
export default function ErrorPage() {
// This will throw an error during render, which will be caught by ErrorBoundary
throw new Error('Test error for ErrorBoundary - this is a render-time error');
}
app/routes/home.tsx
import { useState } from 'react';
import type { Route } from "./+types/home";
import { useAuth } from '../contexts/AuthContext';
import { usePostHog } from '@posthog/react';
export function meta({}: Route.MetaArgs) {
return [
{ title: "Burrito Consideration App" },
{ name: "description", content: "Consider the potential of burritos" },
];
}
export default function Home() {
const { user, login } = useAuth();
const posthog = usePostHog();
const [username, setUsername] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState('');
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
setError('');
try {
const success = await login(username, password);
if (success) {
// Identifying the user once on login/sign up is enough.
posthog?.identify(username);
// Capture login event
posthog?.capture('user_logged_in');
setUsername('');
setPassword('');
} else {
setError('Please provide both username and password');
}
} catch (err) {
console.error('Login failed:', err);
setError('An error occurred during login');
}
};
if (user) {
return (
<div className="container">
<h1>Welcome back, {user.username}!</h1>