Skip to content
trackbridge

trackbridge-setup

The first-time install skill. Detects your package manager from the lockfile, installs both packages, creates lib/tracker.client.ts and lib/tracker.server.ts, and writes the env-var template. Leaves you with empty trackers ready to fire calls.

It does not obtain Google Ads API secrets — that’s trackbridge-ads-oauth. It also doesn’t fire any real conversions — that’s trackbridge-conversions.

Frontmatter

Section titled “Frontmatter”
name: trackbridge-setup
description: Use when adding Trackbridge to a project for the first time, installing @trackbridge/browser or @trackbridge/server, creating the initial tracker instances, or wiring the env vars Trackbridge needs.

When it triggers

Section titled “When it triggers”
  • “Install Trackbridge”
  • “Add @trackbridge/browser to this project”
  • “Set up the trackers”
  • First-time integration mentions, dispatched from the router

Prerequisites

Section titled “Prerequisites”
  • A project with a lockfile (pnpm-lock.yaml, bun.lock / bun.lockb, package-lock.json, or yarn.lock). If none exists, the skill asks which package manager to use.
  • A framework context (Next.js, Vite, SvelteKit, Astro, Nuxt, etc.) — used to pick the right env-var prefix and the canonical paths for tracker modules.

What it touches

Section titled “What it touches”

Files created (or modified if they already exist):

  • lib/tracker.client.ts — browser tracker module.
  • lib/tracker.server.ts — server tracker module (with import 'server-only' where the framework supports it).
  • .env.local — placeholder values, gitignored.
  • .env.example — committed template with empty values and per-var comments.

The exact paths adapt to framework conventions: app/lib/... for Next.js App Router, src/lib/... for Vite/SvelteKit, etc.

What it asks

Section titled “What it asks”
  • Which package manager (only if no lockfile is present).
  • Whether to install both packages or only one (defaults to both — dual-send needs both).
  • Framework confirmation if the skill can’t infer from package.json alone.

What it won’t do

Section titled “What it won’t do”

What it produces

Section titled “What it produces”
lib/tracker.client.ts
import { createBrowserTracker } from '@trackbridge/browser';


export const tracker = createBrowserTracker({
  adsConversionId: process.env.NEXT_PUBLIC_GOOGLE_ADS_CONVERSION_ID!,
  ga4MeasurementId: process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!,
  consentMode: 'v2',
  debug: process.env.NODE_ENV !== 'production',
});
lib/tracker.server.ts
import 'server-only';
import { createServerTracker } from '@trackbridge/server';


export const serverTracker = createServerTracker({
  ga4MeasurementId: process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!,
  ga4ApiSecret: process.env.GA4_API_SECRET!,
  ads: {
    developerToken: process.env.GOOGLE_ADS_DEVELOPER_TOKEN!,
    customerId: process.env.GOOGLE_ADS_CUSTOMER_ID!,
    refreshToken: process.env.GOOGLE_ADS_REFRESH_TOKEN!,
    clientId: process.env.GOOGLE_OAUTH_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_OAUTH_CLIENT_SECRET!,
    conversionActions: {
      purchase: 'customers/REPLACE_ME/conversionActions/REPLACE_ME',
    },
  },
  debug: process.env.NODE_ENV !== 'production',
});
.env.local
# Public — sent to the browser
NEXT_PUBLIC_GOOGLE_ADS_CONVERSION_ID="AW-XXXXXXXXX"
NEXT_PUBLIC_GA4_MEASUREMENT_ID="G-XXXXXXXXXX"


# Server-only — never expose
GA4_API_SECRET=""
GOOGLE_ADS_DEVELOPER_TOKEN=""
GOOGLE_ADS_CUSTOMER_ID=""
GOOGLE_ADS_REFRESH_TOKEN=""
GOOGLE_OAUTH_CLIENT_ID=""
GOOGLE_OAUTH_CLIENT_SECRET=""

The env-var prefixes adapt to the framework (VITE_* for Vite, PUBLIC_* for SvelteKit/Astro, etc.). The skill picks the right prefix from the detected framework.

Example

Section titled “Example”
You: Set up Trackbridge in this project.


Claude (router → setup): I see pnpm-lock.yaml, so I'll use pnpm.
This is a Next.js App Router project, so I'll create the tracker
modules under lib/ and use NEXT_PUBLIC_ prefixes for browser env vars.


[runs: pnpm add @trackbridge/browser @trackbridge/server]


Created lib/tracker.client.ts.
Created lib/tracker.server.ts (with import 'server-only').
Updated .env.local with placeholder values.
Created .env.example as a committed template.


The server-only secrets (GA4_API_SECRET, GOOGLE_ADS_*, GOOGLE_OAUTH_*)
are empty. To fill them in, invoke trackbridge-ads-oauth — that walks
the developer-token / OAuth / refresh-token flow.


To fire your first conversion (once you have the secrets and a
conversion action mapped), invoke trackbridge-conversions.

Verification step

Section titled “Verification step”

The skill’s last step is a temporary “smoke test” call:

import { tracker } from '@/lib/tracker.client';
await tracker.trackConversion({ label: 'purchase', value: 1, currency: 'USD' });

With debug: true, the SDK warns:

[trackbridge] ⚠️ trackConversion called without transactionId
  → Auto-generated: tb_a8f3c1d2-...
  → Dual-send disabled for this call. Pass a transactionId you control...

Seeing this warning proves the SDK is loaded and reachable. The skill then removes the temporary call.

See also

Section titled “See also”