Next.js

Keep initialization in a small Client Component and render it from the root layout. The rest of the layout can remain a Server Component.

Initialize Tracwell

components/tracwell-analytics.tsx

"use client";

import { useEffect } from "react";
import { createTracwell, type TracwellClient } from "tracwell";

let analytics: TracwellClient | undefined;

export function TracwellAnalytics() {
  useEffect(() => {
    analytics ??= createTracwell({
      collectionMode: "product",
      projectKey: "tw_live_...",
    });
  }, []);

  return null;
}

// Render <TracwellAnalytics /> once inside app/layout.tsx.
// Pages Router apps can render it from pages/_app.tsx instead.

Do not call page() from usePathname. Next.js link and router navigation update browser history, which the SDK already observes.

Track an event

Keep the initialized client available to the components or services that own successful product outcomes, then call track() after the outcome completes.

TypeScript

const eventId = analytics.track("signup_completed", {
  plan: "starter",
  source: "pricing",
});

if (!eventId) {
  // Collection is blocked or the event did not pass validation.
}

Continue with the custom events guide for naming, property limits, and verification.