PostHog

PostHogAnalytics is the Analytics component’s PostHog backend. It wraps the official posthog-node client to capture product events from the server, attaching a distinct user id, event properties, and optional groups. It implements the framework’s IAnalytics interface, so call sites stay provider-agnostic and you can swap the backend without touching the code that emits events.

What PostHog captures

Events go straight from your backend through posthog-node, with no client SDK required. capture() takes a typed payload made up of a distinct id, an event name, properties, and optional groups. By default it points at the EU cloud, and you can repoint it at the US cloud or a self-hosted instance. Before the process exits, shutdown() flushes whatever events are still buffered. The class registers with @decorator.analytics() and resolves from the container.

Installation

PostHogAnalytics ships with @talosjs/analytics and depends on the PostHog Node client.

bun add @talosjs/analytics posthog-node

Environment variables

Variable	Required	Purpose
`ANALYTICS_POSTHOG_PROJECT_TOKEN`	Yes	PostHog project API key. Missing throws `AnalyticsException` (`API_KEY_REQUIRED`).
`ANALYTICS_POSTHOG_HOST`	No	PostHog instance host. Defaults to `https://eu.i.posthog.com`.

ANALYTICS_POSTHOG_PROJECT_TOKEN=phc_xxxxxxxxxxxxxxxxxxxxxxxx
# Use the US cloud or a self-hosted instance instead of the EU default:
ANALYTICS_POSTHOG_HOST=https://us.i.posthog.com

The project token is validated when PostHogAnalytics is constructed, so a missing token fails fast at startup.

How it works

On construction, the backend creates a single PostHog client pointed at your host. Each capture() call maps your payload onto a PostHog event: the id becomes the distinctId, properties are sent under $set, the current timestamp is attached, and any groups are forwarded. Capture is fire-and-forget. The client buffers events and flushes them in the background.

Method	Purpose
`capture(options)`	Queue an event for the given distinct id.
`shutdown()`	Flush buffered events and close the client.

The capture payload:

Field	Type	Purpose
`id`	`string`	Distinct id of the user or entity the event belongs to.
`event`	`string`	Event name, e.g. `"order_completed"`.
`properties`	`Record<string, unknown>`	Optional event properties; sent as `$set`.
`groups`	`Record<string, string \| number>`	Optional group analytics keys.

Usage

import { container } from "@talosjs/container";
import { PostHogAnalytics } from "@talosjs/analytics";

const analytics = container.get(PostHogAnalytics);

// Capture an event
analytics.capture({
  id: "user_123",
  event: "order_completed",
  properties: {
    orderId: "ord_456",
    total: 4200,
    currency: "EUR",
  },
});

// Group analytics
analytics.capture({
  id: "user_123",
  event: "feature_used",
  properties: { feature: "export" },
  groups: { company: "acme_inc" },
});

// Flush before the process exits
await analytics.shutdown();

Inject it into a service to record events as part of your domain logic:

import { inject } from "@talosjs/container";
import { PostHogAnalytics } from "@talosjs/analytics";

export class CheckoutService {
  constructor(
    @inject(PostHogAnalytics) private readonly analytics: PostHogAnalytics,
  ) {}

  public async completeOrder(userId: string, order: Order) {
    // ... persist the order ...
    this.analytics.capture({
      id: userId,
      event: "order_completed",
      properties: { orderId: order.id, total: order.total },
    });
  }
}

Use in the app

In an @talosjs/app application, analytics isn’t a dedicated App config slot. PostHogAnalytics registers itself with the container through @decorator.analytics() as soon as the class is imported, and you resolve or inject it wherever you record events.

bun add @talosjs/app @talosjs/analytics posthog-node

Inject it into a service or controller and capture events as part of your domain logic:

import { inject } from "@talosjs/container";
import { PostHogAnalytics } from "@talosjs/analytics";

export class CheckoutService {
  constructor(
    @inject(PostHogAnalytics) private readonly analytics: PostHogAnalytics,
  ) {}

  public async completeOrder(userId: string, order: Order) {
    // ... persist the order ...
    this.analytics.capture({
      id: userId,
      event: "order_completed",
      properties: { orderId: order.id, total: order.total },
    });
  }
}

Because capture is buffered, flush the client before the process exits, for example from a shutdown hook or an onStart handler that registers one:

import { container } from "@talosjs/container";
import { PostHogAnalytics } from "@talosjs/analytics";

process.on("SIGTERM", async () => {
  await container.get(PostHogAnalytics).shutdown();
  process.exit(0);
});

Set ANALYTICS_POSTHOG_PROJECT_TOKEN (and optionally ANALYTICS_POSTHOG_HOST) in your .env.yml (or environment) so the client can initialize.

Exceptions

PostHogAnalytics throws AnalyticsException on misconfiguration, carrying a machine-readable key.

Key	When
`API_KEY_REQUIRED`	`PostHogAnalytics` is constructed without `ANALYTICS_POSTHOG_PROJECT_TOKEN`.

import { AnalyticsException } from "@talosjs/analytics";

try {
  const analytics = container.get(PostHogAnalytics);
} catch (error) {
  if (error instanceof AnalyticsException && error.key === "API_KEY_REQUIRED") {
    logger.error("PostHog is missing its project token", error.data);
  }
  throw error;
}

Getting clean data

Flush with shutdown() before the process terminates, since capture is buffered and the last events would otherwise be lost. Pass a consistent id per user or entity so their events stitch together into one timeline. A naming convention like noun_verb (order_completed, user_signed_up) keeps events easy to query later. Load the project token from .env instead of hard-coding it. The default host is the EU cloud, so override ANALYTICS_POSTHOG_HOST if your data lives in the US cloud or on a self-hosted instance. See the Analytics component for the provider interface and how events flow through the framework.

Getting Started

AI

Framework

Command Line

What PostHog captures

Installation

Environment variables

How it works

Usage

Use in the app

Exceptions

Getting clean data

​What PostHog captures

​Installation

​Environment variables

​How it works

​Usage

​Use in the app

​Exceptions

​Getting clean data

What PostHog captures

Installation

Environment variables

How it works

Usage

Use in the app

Exceptions

Getting clean data