Analytics

PostHog is the single backbone for telemetry: product analytics, web analytics, session replay, plus error tracking and logs over on Monitoring. The kit ships a typed event catalog, automatic identification on login, org-level grouping, and a same-origin reverse proxy so ad blockers and the strict CSP don't get in the way. Every call gates on the NEXT_PUBLIC_POSTHOG_* env vars: a fresh clone with none set ships zero analytics to the browser and captures nothing on the server.

How telemetry flows

Browser and server calls funnel into one PostHog project through a reverse proxy.

The event catalog

Sixteen pre-typed events, organized by surface, enforced at compile time.

Track events

Fire typed events from client components and server contexts.

Add an event

Append to the typed catalog, fire it, build the insight in PostHog.

How Telemetry Flows

The analytics half (browser and server track* calls, identification, group properties) is everything on this page. The rest of the diagram (the onRequestError hook, OTLP logs, source maps) belongs to Monitoring, which shares the same backbone.

The diagram source lives at apps/docs/diagrams/posthog-topology.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Package Layout

Each subpath is exported separately, so consumers import @syntaxkit/analytics/client, /server, /events, or /logger without pulling in the others. The browser bundle never sees the Node SDK; the server never imports posthog-js.

The Event Catalog

Sixteen events ship pre-typed, organized by surface. The catalog is a discriminated union, so track(name, properties) rejects mismatched property shapes at compile time.

export type AnalyticsEvent =
  | { name: "user_signed_up"; properties: { method: AuthMethod } }
  | {
      name: "subscription_started";
      properties: { plan: string; interval: "monthly" | "yearly" };
    }
  // ... 14 more

export type EventName = AnalyticsEvent["name"];
export type EventProperties<N extends EventName> = Extract<
  AnalyticsEvent,
  { name: N }
>["properties"];

Tracking Events From The Client

Import from @syntaxkit/analytics/client and call track:

"use client";
import { track } from "@syntaxkit/analytics/client";

await signIn.email({ email, password });
track("user_logged_in", { method: "email" });

The same SDK exports a few identity and consent helpers:

Tracking Events From The Server

Server contexts (oRPC handlers, Better Auth callbacks, Stripe webhooks) use trackServer from @syntaxkit/analytics/server. The PostHog Node singleton runs with flushAt: 1, flushInterval: 0, so every capture flushes synchronously and the helper is await-able:

import { trackServer } from "@syntaxkit/analytics/server";

await trackServer(userId, "subscription_started", {
  plan: "pro",
  interval: "monthly",
});

Identification And Org Groups

apps/web/components/analytics/identify-user.tsx is a tiny client component mounted in the root layout. It identifies the user on login, resets on logout, and sets the active org as a PostHog group:

"use client";
import { useEffect, useRef } from "react";
import { useSession } from "@/lib/auth-client";
import { identify, reset, setGroup } from "@syntaxkit/analytics/client";

export function IdentifyUser() {
  const { data: session } = useSession();
  // ...
  useEffect(() => {
    if (session?.user) {
      identify(session.user.id, {
        email: session.user.email,
        name: session.user.name,
      });
    } else {
      reset();
    }
  }, [session]);

  // setGroup("organization", activeOrgId, { name, member_count, created_at })
  // runs once the active org loads.
}

The setGroup call powers org-level analysis: per-org funnels, retention by plan, conversion by member count. It's worth doing even before you have a question to answer: PostHog backfills group data into historical events as soon as the group is set.

Web Analytics And Session Replay

PostHog's auto-capture covers page views, clicks, and form interactions out of the box via the kit's defaults: "2026-01-30" config, no tag-by-tag wiring. Session replay is enabled in production and disabled in dev:

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: "/ingest",
  ui_host: process.env.NEXT_PUBLIC_POSTHOG_UI_HOST,
  defaults: "2026-01-30",
  disable_session_recording: process.env.NODE_ENV === "development",
});

Replays auto-link to errors captured via captureError, so a failed signup gives you both the stack trace and a 30-second video of what the user saw and clicked.

Adding A New Event

| { name: "your_event"; properties: { foo: string; count: number } }

track("your_event", { foo: "bar", count: 1 });

await trackServer(userId, "your_event", { foo: "bar", count: 1 });

Graceful Degradation

Leave the env vars unset and the integration disappears. To swap providers, replace the four files in packages/analytics/src/ and keep the same public API. The rest of the app doesn't change.

Where To Go Next