Quickstart: Next.js — Docs

OakData ships as oakdata-js, a zero-config tracker for the browser. On Next.js (App Router, 15.1+) the cleanest install point is instrumentation-client.ts — a file Next.js runs once on the client before your app hydrates, so pageviews and autocapture start immediately.

1. Install the package

npm install oakdata-js

2. Add your keys

Create (or edit) .env.local at your project root. The NEXT_PUBLIC_prefix is required — these values run in the browser. Use your project's public key (oak_pub_…); never put a secret key here.

.env.local

bash

NEXT_PUBLIC_OAK_KEY=oak_pub_xxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_OAK_HOST=https://oakdata.co

3. Initialize the tracker

Create instrumentation-client.ts at your project root (next to app/, not inside it):

instrumentation-client.ts

import oak from 'oakdata-js'

oak.init(process.env.NEXT_PUBLIC_OAK_KEY!, {
  api_host: process.env.NEXT_PUBLIC_OAK_HOST,
})

That's it. Pageviews fire on load and on every client-side route change, and clicks, form submits, and other interactions are autocaptured automatically.

Older Next.js?

On versions before instrumentation-client.ts support, call oak.init() from a small client component mounted in your root layout (a "use client" component that runs oak.init inside a useEffect with an empty dependency array). Calling initmore than once is a no-op, so it's safe.

4. Identify signed-in users

After a user signs in or signs up, call identify with their id and any traits you want to see in the dashboard. Calls made before init() are queued and replayed, so it's safe to call oak.identify from anywhere.

after-signin.ts

import oak from 'oakdata-js'

oak.identify(user.id, {
  email: user.email,
  name: user.name,
})

On sign-out, call oak.reset() to clear the stored ids and start a fresh anonymous identity. See identity resolution for how anonymous and identified activity are stitched together.

5. Track custom events

Beyond autocapture, send your own events with capture:

checkout.ts

import oak from 'oakdata-js'

oak.capture('signup_completed', { plan: 'pro' })

Read the full SDK reference for every method and init option.