Add analytics to Remix with Tracwell

Track page views and custom events in Remix. Learn where to initialize Tracwell, avoid duplicate tracking, and verify your installation.

Guide reviewed

Initialize Tracwell

Create the client in one module and start it from app/root.tsx. The effect is skipped during server rendering and stays mounted across nested routes.

pnpm add tracwell
app/analytics.ts
import { createTracwell, type TracwellClient } from "tracwell";

let client: TracwellClient | undefined;

export function startAnalytics() {
  client ??= createTracwell({
    collectionMode: "private",
    projectKey: "tw_live_...",
  });
}

/** Undefined during server rendering and before startAnalytics() runs. */
export function getAnalytics() {
  return client;
}

// In app/root.tsx:
// useEffect(() => startAnalytics(), []);

Replace tw_live_... with your project key from Settings → Website → Tracking setup.

Remix client transitions use React Router and browser history, so the SDK records route changes automatically.

Track an event

Call track() after a product action succeeds, from wherever that action completes:

Any route component
import { getAnalytics } from "~/analytics";

getAnalytics()?.track("signup_completed", { plan: "starter" });

The optional call (?.) skips tracking whenever the client is not available yet, such as during server rendering. Continue with the custom events guide for naming, property limits, and verification.

Track navigation without duplicate page views

Tracwell records the initial page view and observes standard History API navigation, including pushState, replaceState, and back or forward navigation. Do not add another page-view call for the same route change. Hash-only changes are ignored; call page() only for meaningful page changes that do not update browser history.

Verify the installation

  1. Copy the project key from Settings → Website → Tracking setup. To test locally, add a separate website whose URL is your local address, such as http://localhost:3000; the port must match.
  2. Open the website with the SDK installed. If consent is required, grant it through your site’s consent flow before expecting collection.
  3. Confirm the initial page view in Tracwell’s Realtime report, then use a normal internal link and check that the destination is recorded once.
  4. Complete the custom action and check its name and properties in Events → live stream. If nothing arrives, follow the troubleshooting checklist.
Troubleshoot missing events

Turn events into conversion reports

Use successful product actions as goal matches or steps in an ordered funnel. Verified purchases and refunds must come from your backend; a browser checkout click is not payment confirmation.