Analytics

On This Page

How Telemetry FlowsBrowser and server events share one PostHog project. Browser traffic uses the /ingest proxy.Package LayoutClient, server, events, and logger entry points under packages/analytics.The Event CatalogSixteen typed events. Wrong property shapes fail at compile time.Tracking Events From The ClientFire typed events and use identify, reset, and consent helpers.Tracking Events From The ServerAwait trackServer in oRPC handlers, auth callbacks, and webhooks.Identification And Org GroupsIdentify on login, reset on logout, set the active org as a group.Web Analytics And Session ReplayAuto-capture page views and clicks. Replays on in production.Adding A New EventAdd it to the catalog, fire it, then build the insight in PostHog.Graceful DegradationNo PostHog key means no capture. No warnings, no broken UI.

How Telemetry Flows

This page covers product events: track / trackServer, identification, and org groups. The diagram also shows error capture, OTLP logs, and source maps. Those belong to Monitoring. Both pages share the same PostHog project and /ingest proxy.

Browser SDK calls go through same-origin /ingest so ad blockers and the CSP stay out of the way. Server calls use posthog-node against the PostHog host directly. Proxy setup details live on Monitoring.

Package Layout

Each subpath is a separate export: @syntaxkit/analytics/client, /server, /events, or /logger. Import only what you need. The browser bundle never sees the Node SDK; the server never imports posthog-js.

The Event Catalog

Sixteen events ship typed and grouped 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 track from @syntaxkit/analytics/client and fire after the action succeeds:

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

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

Client track is fully typed against the catalog. The same module also exports identity and consent helpers:

Tracking Events From The Server

Use trackServer from @syntaxkit/analytics/server in oRPC handlers, Better Auth callbacks, and Stripe webhooks. The PostHog Node client uses flushAt: 1 and flushInterval: 0, so each capture flushes before the promise resolves:

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

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

Known event names still get autocomplete. Properties are Record<string, unknown> on the server so one-off webhook events can compile without a catalog entry.

Identification And Org Groups

apps/web/components/analytics/identify-user.tsx mounts in the root layout. It identifies the user on login, resets on logout, and sets the active organization 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.
}

setGroup unlocks org-level analysis: funnels per org, retention by plan, conversion by member count. PostHog can attach group properties to historical events once the group exists, so wiring it early pays off later.

Web Analytics And Session Replay

You get page views, clicks, and form interactions without tagging each element. The kit inits PostHog with defaults: "2026-01-30". Session replay is on in production and off in development:

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

Replays link to errors from captureError, so a failed signup gives you the stack trace and a short video of what the user saw. Error capture itself is documented on Monitoring.

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 key unset and the integration stays off. To swap providers, replace the four files in packages/analytics/src/ and keep the same public API. The rest of the app stays the same.

Where To Go Next

Also useful: Billing and Setup.