Code in your repo
The files Torque Lift generates in your repo, the functions they export, the environment variables they read, and when they send nothing.
Torque Lift adds a small wrapper to your repo in the second pull request. It is generated from torque-lift/tracking-plan.yaml, so you review the plan first and the code second. This page lists what the wrapper exports, so you can read the diff with the types in front of you.
Don't edit the generated files
Torque Lift regenerates them from the plan. To change what is tracked, change the plan in a pull request. A test in the pull request fails if analytics.events.ts no longer matches the plan.
The files
The wrapper lives in lib/ next to your app (under the app's path in a monorepo). It sends events to Jitsu, the open-source collector that lands them in your bucket.
| File | What it is |
|---|---|
analytics.ts | The browser wrapper around @jitsu/js. |
analytics.events.ts | Types for every event, property and trait in the plan, and the plan's global properties. |
analytics.provider.tsx | TorqueLiftAnalytics, mounted once. The Next.js Pages Router, Vite, and Remix or React Router apps each get a provider written for their router. |
analytics.server.ts | trackServer, only when the plan has server: true events. Not written for Vite apps, which have no server. |
analytics.flags.tsx | TorqueLiftFlag, added by the first experiment pull request. |
analytics.plan.test.ts | Fails if analytics.events.ts and the plan disagree. |
analytics.fire.test.ts | Fires each plan event against a fake collector. Only added if your repo already has a DOM test environment. |
Environment variables
Set these in production before you merge the tracking pull request. The pull request lists them too.
| Variable | Used by | What it holds |
|---|---|---|
NEXT_PUBLIC_TORQUELIFT_WRITE_KEY | analytics.ts | The write key for your collector. |
NEXT_PUBLIC_TORQUELIFT_JITSU_HOST | analytics.ts, analytics.server.ts | Your collector's address. |
TORQUELIFT_JITSU_SERVER_KEY | analytics.server.ts | The server-to-server key. Never exposed to the browser. |
NEXT_PUBLIC_TORQUELIFT_GB_CLIENT_KEY | analytics.flags.tsx | The GrowthBook client key. |
NEXT_PUBLIC_TORQUELIFT_GB_API_HOST | analytics.flags.tsx | A full https:// URL for your GrowthBook endpoint. |
In a Vite, Remix or React Router app the public names start with VITE_ instead of NEXT_PUBLIC_. The generated code reads them with the form your build tool inlines.
When nothing is sent
analytics.ts sends nothing, and logs the call to the console instead, when any of these is true:
- The write key or collector host isn't set.
- A script is driving the browser (
navigator.webdriveris set). - Analytics consent hasn't been recorded as
true.
It also sends no IP address, and no query string, fragment or page title. Pages are named by route template, such as /projects/[id], never by URL. Only utm_source, utm_medium and utm_campaign, and the referrer's host, are kept from where a visitor landed, in memory only.
analytics.ts
import {
setAnalyticsConsent,
track,
page,
identify,
reset,
onIdentity,
trackExposure,
} from "@/lib/analytics";| Function | What it does |
|---|---|
setAnalyticsConsent(granted: boolean) | Records the visitor's consent. Nothing is sent and no cookie is set until it is true. Calling it with true also sends the page view for the page the visitor accepted on. |
track(event, properties?) | Sends a plan event. Only events and properties in the plan type-check, and properties is required when the plan has a required property. |
page(routeTemplate) | Sends a page view named by its route template. The provider calls this on every navigation. |
identify(userId, traits?) | Ties this browser to the signed-in user, with the plan's traits only. |
reset() | Forgets the user and starts a new anonymous ID. Returns a promise: await it before redirecting on logout. |
onIdentity(listener) | Calls listener now, and after each identify of a new user, each reset and each change of consent. Returns a function that removes it. analytics.flags.tsx uses it. |
trackExposure(exposure) | Sends Experiment Viewed. Only analytics.flags.tsx calls it. |
Call track where the event happens:
import { track } from "@/lib/analytics";
export function CheckoutButton({ tier }: { tier: "pro" | "team" }) {
return (
<button onClick={() => track("Checkout Started", { plan_tier: tier })}>
Start checkout
</button>
);
}Checkout Started is the event from the example plan. An event or property that isn't in your plan is a type error.
Recording consent
Your app decides when a visitor has agreed. Pass it to the provider, or call setAnalyticsConsent when your banner answers:
import { setAnalyticsConsent } from "@/lib/analytics";
onAccept(() => setAnalyticsConsent(true));
onReject(() => setAnalyticsConsent(false));analytics.provider.tsx
TorqueLiftAnalytics renders nothing. Mount it once, in the root layout (Next.js App Router), in pages/_app (Pages Router), inside <body> of the root route (Remix and React Router), or in the entry file (Vite). The pull request adds the mount line for you.
| Prop | Type | What it does |
|---|---|---|
userId | string | null | undefined | The signed-in user, from the source the plan names. Calls identify when it appears and reset when it goes away. |
traits | IdentifyTraits | The plan's traits. A change sends a new identify. |
consent | boolean | Your visitor's consent. Leave it out to call setAnalyticsConsent yourself. |
<TorqueLiftAnalytics userId={session?.user.id} consent={consent} />In Vite, Remix and React Router apps there is no file-system router, so the provider matches the URL to the plan's page routes. A path that matches none sends no page view, so a URL is never sent as a page name.
analytics.server.ts
For plan events marked server: true, such as a payment confirmed by a webhook. Subscription Started here stands for one of your own plan's server events.
import { trackServer } from "@/lib/analytics.server";
await trackServer("Subscription Started", {
userId: user.id,
messageId: stripeEvent.id,
properties: { plan_tier: "team" },
});userId and messageId are required. Use the source's own event ID as messageId, such as a Stripe event ID, so a retry doesn't count twice. trackServer never throws into the route that calls it: it logs and carries on. It throws only if you call it in the browser.
analytics.flags.tsx
Added by an experiment pull request. It uses the OpenFeature React SDK with GrowthBook's client provider.
import { TorqueLiftFlag } from "@/lib/analytics.flags";
<TorqueLiftFlag flag="checkout-copy" variant={<NewCheckoutCopy />}>
<ExistingCheckoutCopy />
</TorqueLiftFlag>| Prop | What it does |
|---|---|
flag | The flag's key. |
variant | What shows where the flag is on. It lives in new files. |
children | Today's version, which shows everywhere else. |
Every flag is off, so your visitors see today's version, when any of these is true:
- It runs on the server, or before analytics consent. Nothing is fetched or stored before consent.
NEXT_PUBLIC_TORQUELIFT_GB_CLIENT_KEYorNEXT_PUBLIC_TORQUELIFT_GB_API_HOSTisn't set, or the host isn't a fullhttps://URL.- The experiment buckets by signed-in user and nobody is signed in.
- GrowthBook doesn't answer within one second.
When someone withdraws consent, GrowthBook stops and its stored features are removed. Each assignment sends one Experiment Viewed event, with the route template where the flag was evaluated. See Experiments.
Next
- Tracking for the plan file the wrapper is generated from.
- Event tables for where each call lands in your bucket.
- Troubleshooting if events aren't arriving.