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 tracwellimport { 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.
Track an event
Call track() after a product action succeeds, from wherever that action completes:
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.
Choose collection and consent settings
The example uses Private mode, the default: no cookies or browser storage, with visitors estimated each day. Switch collectionMode to "product" only if you need identify(), returning visitors or revenue attribution, and make the same change in Settings → Website → Tracking setup. Product mode stores identity in localStorage, so add consent: "required" and call setConsent() from your consent banner where the law requires it. Do Not Track is respected by default, so a browser with it enabled sends nothing while you test.
Configure consent and privacyVerify the installation
- 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.
- Open the website with the SDK installed. If consent is required, grant it through your site’s consent flow before expecting collection.
- Confirm the initial page view in Tracwell’s Realtime report, then use a normal internal link and check that the destination is recorded once.
- Complete the custom action and check its name and properties in Events → live stream. If nothing arrives, follow the troubleshooting checklist.
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.