Analytics

The @talosjs/analytics component tracks product events, user behavior, and metrics. It provides an IAnalytics interface and a @decorator.analytics() decorator so you can build typed, purpose-specific tracking classes, register them with the container, and send events to whatever backend you choose.

The shape of it

There is one method to learn: capture() records an event from a typed options object. Each analytics class defines its own capture options type rather than passing around an untyped bag of fields, and registration is a decorator away, so the container handles resolution and lifecycle for you. The interface is the only contract, which means you can point IAnalytics at any sink (a data warehouse, an HTTP endpoint, a queue) and the call sites never change.

How it works

You define an analytics class, implement capture() with your tracking logic, and register it with @decorator.analytics(). The container manages its lifecycle; callers resolve the class and call capture() with a typed options object.

container.get(MyAnalytics)        // resolve the registered class
  → analytics.capture(options)    // your implementation forwards the event
  → your backend                  // warehouse, HTTP endpoint, queue, ...

Since the interface is the only contract, you can swap or stub the backend without touching any call site.

Decorator and usage

`@decorator.analytics()`

Registers an analytics class with the container. It accepts an optional scope (defaults to singleton).

import { decorator } from "@talosjs/analytics";
import type { IAnalytics } from "@talosjs/analytics";

type PageViewOptionsType = {
  id: string;
  event: string;
  properties?: Record<string, unknown>;
};

@decorator.analytics()
export class PageViewAnalytics implements IAnalytics<PageViewOptionsType> {
  public capture(options: PageViewOptionsType): void {
    // Tracking logic for page views.
  }
}

Resolve it from the container and call capture():

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

const analytics = container.get(PageViewAnalytics);
analytics.capture({
  id: "user-123",
  event: "page_view",
  properties: { page: "/pricing" },
});

Choose a non-default scope when you need a fresh instance per request:

import { EContainerScope } from "@talosjs/container";

@decorator.analytics(EContainerScope.Request)
export class RequestAnalytics implements IAnalytics {
  public capture(options: Record<string, unknown>): void {
    // New instance per HTTP request.
  }
}

Capturing events

capture() takes the typed options object your class defines, so model it on the event you track. Keep one class per concern and each one ends up with a precise shape.

type PurchaseOptionsType = {
  id: string;
  event: string;
  properties?: Record<string, unknown>;
  groups?: Record<string, string | number>;
};

@decorator.analytics()
export class PurchaseAnalytics implements IAnalytics<PurchaseOptionsType> {
  public capture(options: PurchaseOptionsType): void {
    // Forward the event to your backend.
  }
}

const analytics = container.get(PurchaseAnalytics);
analytics.capture({
  id: "user-123",
  event: "purchase_completed",
  properties: {
    productId: "prod-456",
    price: 99.99,
    currency: "USD",
  },
});

Exceptions

The component ships AnalyticsException for signaling analytics failures from your implementation. It carries a machine-readable key, a human-readable message, and a data object, so callers can branch on the key.

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

@decorator.analytics()
export class PurchaseAnalytics implements IAnalytics<PurchaseOptionsType> {
  public capture(options: PurchaseOptionsType): void {
    if (!options.id) {
      throw new AnalyticsException("Missing user id", "USER_ID_REQUIRED", {
        event: "purchase_completed",
      });
    }
    // Forward the event to your backend.
  }
}

Catch it at the call site to handle analytics errors without breaking the request:

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

try {
  analytics.capture(options);
} catch (error) {
  if (error instanceof AnalyticsException) {
    logger.error(`Analytics error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Keeping events clean

Replace Record<string, unknown> with a precise options type per class so events stay consistent. Give each tracked concern its own class (a PageViewAnalytics, a CheckoutAnalytics, and so on); small, focused classes are easier to test and reason about. Pick a naming convention and hold to it, for example snake_case verbs like purchase_completed or button_clicked, which keeps dashboards readable. Load any keys your implementation needs from .env and never hard-code them. The built-in PostHogAnalytics reads ANALYTICS_POSTHOG_PROJECT_TOKEN and optionally ANALYTICS_POSTHOG_HOST. Treat capture() as fire-and-forget: it returns void, so keep it lightweight and off the request’s critical path. When you throw AnalyticsException, keep the key constant per failure so callers can branch on it, and put the variable detail in data.

CLI command

Scaffold an analytics class and its test file with the generator. It writes the class under modules/<module>/src/analytics/<Name>Analytics.ts and installs @talosjs/analytics if it is missing.

# Interactive: prompts for the name
talos analytics:create

# Provide the name
talos analytics:create --name=PageView

# Target a module and overwrite
talos analytics:create --name=PageView --module=tracking --override

Option	Description	Default
`--name`	Analytics class name. The `Analytics` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class starts from this shape, ready for you to type the options and implement capture():

import { decorator } from "@talosjs/analytics";
import type { IAnalytics } from "@talosjs/analytics";

type CaptureOptionsType = Record<string, unknown>;

@decorator.analytics()
export class PageViewAnalytics<T extends CaptureOptionsType = CaptureOptionsType>
  implements IAnalytics<T>
{
  public capture(options: T): void {
    // console.log("Analytics captured:", options);
  }
}

See analytics:create for the full command reference.

Use with Claude and Codex

The generator ships a matching analytics:create skill. It runs the scaffold and then guides your AI agent through completing the class: defining a proper capture options type and implementing the tracking logic in capture(). Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Add analytics for page views that captures the user id and page path.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Add analytics for page views that captures the user id and page path.

For example, the prompt above maps to analytics:create --name=PageView, then types the capture options and implements capture().

Getting Started

AI

Framework

Command Line

The shape of it

How it works

Decorator and usage

`@decorator.analytics()`

Capturing events

Exceptions

Keeping events clean

CLI command

Use with Claude and Codex

​The shape of it

​How it works

​Decorator and usage

​@decorator.analytics()

​Capturing events

​Exceptions

​Keeping events clean

​CLI command

​Use with Claude and Codex

The shape of it

How it works

Decorator and usage

`@decorator.analytics()`

Capturing events

Exceptions

Keeping events clean

CLI command

Use with Claude and Codex