@trackbridge/sdk/next

The Next.js adapter ships in two subpaths:

• @trackbridge/sdk/next — React-side helpers, marked 'use client' where required. Loads gtag.js, wires consent defaults, exposes the tracker via context.
• @trackbridge/sdk/next/server — Node-side helpers for route handlers and Server Actions. Cached factory + envelope reader.

You can use Trackbridge in Next.js without this adapter — createBrowserTracker and createServerTracker work fine in any framework. The adapter exists to remove the boilerplate that almost every Next.js integration writes:

• A 'use client' provider that creates the tracker once and exposes it via useContext.
• A page-views component that wires usePathname to tracker.trackPageView.
• A consent-default snippet that runs beforeInteractive so gtag respects denied state from the first hit.
• A module-level singleton wrapper around createServerTracker so route handlers don’t re-construct it on every request.

Client-side exports

import {
  TrackbridgeProvider,
  TrackbridgePageViews,
  useTracker,
} from '@trackbridge/sdk/next';

Export	Use
<TrackbridgeProvider>	Wrap your app/layout.tsx. Loads gtag.js, sets Consent Mode v2 defaults, creates the tracker once, exposes via context.
<TrackbridgePageViews />	Drop into the same layout. Fires trackPageView on every Next.js route change.
useTracker()	Hook returning the BrowserTracker. Throws if used outside <TrackbridgeProvider>.

The adapter also re-exports BrowserTracker, BrowserTrackerConfig, ConsentState, ConsentValue, ConsentUpdate, ClickIdentifiers, TrackbridgeContext, and TrackbridgeItem so client components don’t have to dual-import from /browser.

Server-side exports

import {
  defineServerTracker,
  readEnvelopeFromRequest,
} from '@trackbridge/sdk/next/server';

Export	Use
defineServerTracker(configFn)	Module-level singleton wrapper. First call creates the tracker; subsequent calls return the cached instance. Errors are cached and re-thrown without re-running configFn.
readEnvelopeFromRequest({ headers, cookies })	Reads _tb_* / _ga cookies and the optional x-trackbridge-context header into a partial TrackbridgeContext ready for serverTracker.fromContext(envelope).

The server adapter also re-exports ServerTracker, ServerTrackerConfig, and TrackbridgeContext.

See also

• Next.js App Router setup guide — end-to-end wiring with both adapters.
• @trackbridge/sdk/browser — what the React provider wraps.
• @trackbridge/sdk/server — what defineServerTracker wraps.