# PostHog astro-ssr Example Project Repository: https://github.com/PostHog/context-mill Path: basics/astro-ssr --- ## README.md # PostHog Astro SSR Example This is an [Astro](https://astro.build/) server-side rendered (SSR) example demonstrating PostHog integration with both client-side and server-side event tracking. It uses: - **Client-side**: PostHog web snippet for browser analytics - **Server-side**: `posthog-node` for API route event tracking This shows how to: - Initialize PostHog on both client and server - Track events from API routes using `posthog-node` - Pass session IDs from client to server for unified sessions - Identify users on both client and server - Capture errors via `posthog.captureException()` - Reset PostHog state on logout ## Features - **Server-side rendering**: Full SSR with `output: 'server'` - **API routes**: Server-side endpoints for auth and event tracking - **Dual tracking**: Events captured on both client and server - **Session continuity**: Session ID passed to server via headers - **Product analytics**: Track login and burrito consideration events - **Session replay**: Enabled via PostHog snippet configuration - **Error tracking**: Manual error capture sent to PostHog - **Simple auth flow**: Demo login using localStorage + server API ## Getting started ### 1. Install dependencies ```bash npm install # or pnpm install ``` ### 2. Configure environment variables Create a `.env` file in the project root: ```bash # Client-side (PUBLIC_ prefix exposes to browser) PUBLIC_POSTHOG_PROJECT_TOKEN=your_posthog_project_token PUBLIC_POSTHOG_HOST=https://us.i.posthog.com # Server-side (no PUBLIC_ prefix, server-only) POSTHOG_PROJECT_TOKEN=your_posthog_project_token POSTHOG_HOST=https://us.i.posthog.com ``` Get your PostHog project token from your project settings in PostHog. ### 3. Run the development server ```bash npm run dev # or pnpm dev ``` Open `http://localhost:4321` in your browser. ## Project structure ```text src/ components/ posthog.astro # PostHog snippet for client-side tracking Header.astro # Navigation + logout, calls posthog.reset() layouts/ PostHogLayout.astro # Root layout that includes PostHog + Header lib/ auth.ts # Client-side auth utilities posthog-server.ts # Server-side PostHog client singleton pages/ index.astro # Login form, calls /api/auth/login burrito.astro # Burrito demo, calls /api/events/burrito profile.astro # Profile + error tracking demo api/ auth/ login.ts # Server-side login endpoint with PostHog tracking events/ burrito.ts # Server-side event capture endpoint styles/ global.css # Global styles ``` ## Key integration points ### Server-side PostHog client (`src/lib/posthog-server.ts`) A singleton pattern ensures only one PostHog client is created: ```typescript import { PostHog } from "posthog-node"; let posthogClient: PostHog | null = null; export function getPostHogServer(): PostHog { if (!posthogClient) { posthogClient = new PostHog(import.meta.env.POSTHOG_PROJECT_TOKEN, { host: import.meta.env.POSTHOG_HOST, flushAt: 1, flushInterval: 0, }); } return posthogClient; } ``` ### API route with server-side tracking (`src/pages/api/auth/login.ts`) ```typescript import { getPostHogServer } from "../../../lib/posthog-server"; export const POST: APIRoute = async ({ request }) => { const body = await request.json(); const { username } = body; // Get session ID from client const sessionId = request.headers.get("X-PostHog-Session-Id"); const posthog = getPostHogServer(); // Capture server-side event posthog.capture({ distinctId: username, event: "server_login", properties: { $session_id: sessionId || undefined, source: "api", }, }); return new Response(JSON.stringify({ success: true })); }; ``` ### Passing session ID to server (`src/pages/index.astro`) ```javascript // Get the session ID from PostHog to pass to the server const sessionId = window.posthog?.get_session_id?.() || null; const response = await fetch("/api/auth/login", { method: "POST", headers: { "Content-Type": "application/json", "X-PostHog-Session-Id": sessionId || "", }, body: JSON.stringify({ username, password }), }); ``` ### Client-side identification (`src/pages/index.astro`) After server login succeeds, also identify on client: ```javascript window.posthog?.identify(username); window.posthog?.capture("user_logged_in"); ``` ### Logout and session reset (`src/components/Header.astro`) On logout, both the local auth state and PostHog state are cleared: ```javascript window.posthog?.capture("user_logged_out"); localStorage.removeItem("currentUser"); window.posthog?.reset(); ``` ## Scripts ```bash # Run dev server npm run dev # Build for production npm run build # Preview production build npm run preview ``` ## Learn more - [PostHog documentation](https://posthog.com/docs) - [PostHog Astro guide](https://posthog.com/docs/libraries/astro) - [PostHog Node.js SDK](https://posthog.com/docs/libraries/node) - [Astro SSR documentation](https://docs.astro.build/en/guides/server-side-rendering/) --- ## .env.example ```example # Client-side environment variables (PUBLIC_ prefix) PUBLIC_POSTHOG_PROJECT_TOKEN=your_posthog_project_token_here PUBLIC_POSTHOG_HOST=https://us.i.posthog.com # Server-side environment variables (no PUBLIC_ prefix) POSTHOG_PROJECT_TOKEN=your_posthog_project_token_here POSTHOG_HOST=https://us.i.posthog.com ``` --- ## astro.config.mjs ```mjs import { defineConfig } from "astro/config"; import node from "@astrojs/node"; export default defineConfig({ output: "server", adapter: node({ mode: "standalone", }), image: { service: { entrypoint: "astro/assets/services/noop" }, }, }); ``` --- ## src/components/Header.astro ```astro --- // Header component with navigation and logout functionality ---
Not logged in
``` --- ## src/components/posthog.astro ```astro --- // PostHog analytics snippet for client-side tracking // Uses is:inline to prevent Astro from processing the script --- ``` --- ## src/layouts/PostHogLayout.astro ```astro --- import PostHog from '../components/posthog.astro'; import Header from '../components/Header.astro'; import '../styles/global.css'; interface Props { title: string; } const { title } = Astro.props; --- {title}
``` --- ## src/lib/auth.ts ```ts // Client-side auth utilities for localStorage-based authentication export interface User { username: string; burritoConsiderations: number; } export function getCurrentUser(): User | null { if (typeof window === "undefined") return null; const username = localStorage.getItem("currentUser"); if (!username) return null; const considerations = parseInt( localStorage.getItem("burritoConsiderations") || "0", 10, ); return { username, burritoConsiderations: considerations, }; } export function login(username: string, password: string): boolean { if (!username || !password) return false; localStorage.setItem("currentUser", username); // Initialize burrito considerations if not set if (!localStorage.getItem("burritoConsiderations")) { localStorage.setItem("burritoConsiderations", "0"); } return true; } export function logout(): void { localStorage.removeItem("currentUser"); localStorage.removeItem("burritoConsiderations"); } export function incrementBurritoConsiderations(): number { const current = parseInt( localStorage.getItem("burritoConsiderations") || "0", 10, ); const newCount = current + 1; localStorage.setItem("burritoConsiderations", newCount.toString()); return newCount; } ``` --- ## src/lib/posthog-server.ts ```ts import { PostHog } from "posthog-node"; let posthogClient: PostHog | null = null; /** * Get the PostHog server-side client. * Uses a singleton pattern to avoid creating multiple clients. */ export function getPostHogServer(): PostHog { if (!posthogClient) { posthogClient = new PostHog(import.meta.env.POSTHOG_PROJECT_TOKEN || "", { host: import.meta.env.POSTHOG_HOST || "https://us.i.posthog.com", // Flush immediately for demo purposes // In production, you might want to batch events flushAt: 1, flushInterval: 0, }); } return posthogClient; } /** * Shutdown the PostHog client gracefully. * Call this when your server is shutting down. */ export async function shutdownPostHog(): Promise { if (posthogClient) { await posthogClient.shutdown(); posthogClient = null; } } ``` --- ## src/pages/api/auth/login.ts ```ts import type { APIRoute } from "astro"; import { getPostHogServer } from "../../../lib/posthog-server"; // In-memory user store for demo purposes const users = new Map(); export const POST: APIRoute = async ({ request }) => { try { const body = await request.json(); const { username, password } = body; if (!username || !password) { return new Response( JSON.stringify({ error: "Username and password are required" }), { status: 400, headers: { "Content-Type": "application/json" } }, ); } // Check if this is a new user const isNewUser = !users.has(username); if (isNewUser) { users.set(username, { username, createdAt: new Date().toISOString(), }); } // Get the PostHog server client const posthog = getPostHogServer(); // Get session ID from client if available (passed via header) const sessionId = request.headers.get("X-PostHog-Session-Id"); // Capture server-side login event posthog.capture({ distinctId: username, event: "server_login", properties: { $session_id: sessionId || undefined, isNewUser, source: "api", timestamp: new Date().toISOString(), }, }); // Also identify the user server-side posthog.identify({ distinctId: username, properties: { username, createdAt: isNewUser ? new Date().toISOString() : undefined, }, }); return new Response( JSON.stringify({ success: true, username, isNewUser, }), { status: 200, headers: { "Content-Type": "application/json" } }, ); } catch (error) { console.error("Login error:", error); return new Response(JSON.stringify({ error: "Internal server error" }), { status: 500, headers: { "Content-Type": "application/json" }, }); } }; ``` --- ## src/pages/api/events/burrito.ts ```ts import type { APIRoute } from "astro"; import { getPostHogServer } from "../../../lib/posthog-server"; export const POST: APIRoute = async ({ request }) => { try { const body = await request.json(); const { username, totalConsiderations } = body; if (!username) { return new Response(JSON.stringify({ error: "Username is required" }), { status: 400, headers: { "Content-Type": "application/json" }, }); } // Get the PostHog server client const posthog = getPostHogServer(); // Get session ID from client if available (passed via header) const sessionId = request.headers.get("X-PostHog-Session-Id"); // Capture server-side burrito consideration event posthog.capture({ distinctId: username, event: "burrito_considered", properties: { $session_id: sessionId || undefined, total_considerations: totalConsiderations, source: "api", timestamp: new Date().toISOString(), }, }); return new Response( JSON.stringify({ success: true, totalConsiderations, }), { status: 200, headers: { "Content-Type": "application/json" } }, ); } catch (error) { console.error("Burrito event error:", error); return new Response(JSON.stringify({ error: "Internal server error" }), { status: 500, headers: { "Content-Type": "application/json" }, }); } }; ``` --- ## src/pages/burrito.astro ```astro --- import PostHogLayout from '../layouts/PostHogLayout.astro'; ---

Burrito consideration zone

Take a moment to truly consider the potential of burritos.

Consideration stats

Total considerations: 0

Events are tracked both client-side and server-side for demonstration.

``` --- ## src/pages/index.astro ```astro --- import PostHogLayout from '../layouts/PostHogLayout.astro'; ---

Welcome to Burrito Consideration App

Please sign in to begin your burrito journey

Note: This is a demo app with server-side tracking. Use any username and password to sign in.

``` --- ## src/pages/profile.astro ```astro --- import PostHogLayout from '../layouts/PostHogLayout.astro'; ---

User Profile

Your Information

Username:

Burrito Considerations: 0

Your Burrito Journey

Error Tracking Demo

Click the button below to trigger a test error and send it to PostHog:

 ``` ---