Next.js
Next.js installation, account resolution, and verification.
Next.js is the first-class path. npx atune init detects your framework and
auth, installs the package, and writes your env keys. Follow the
quickstart compatibility notes for the published
installer's proxy.ts / middleware.ts behavior.
Run init
npx atune init# When prompted, paste your workspace API key (Settings → API key)Verify capture wiring
init patches your middleware with createAtuneMiddleware(),
but existing handlers may need manual chaining. Preserve authentication and
custom responses, then verify an attributed request. No account ID means no event.
Ask
import { understand } from "atune";
const r = await understand("account:acme", "how healthy is this account?");See it in a complete app
atune-nextjs-example is a small, public Next.js 16 + Clerk
Organizations app with capture, track(), identify(), understand() and an
MCP config wired in. Copy from it, or point your coding agent at it.
How account detection works
Atune needs the account and user for each request. If your app has teams or organizations, it uses the team/org when available; otherwise it can fall back to the signed-in user. Verify the mapping against your company model before relying on it.
For Clerk, pass the account from your clerkMiddleware callback with
clerkAccount(auth) (atune 0.1.5 or later); see
Chaining with an existing middleware.
Clerk's session can't be read from inside a proxy any other way.
For Supabase, Atune reads the session from the request's cookies through @supabase/ssr (install it
if your app only uses @supabase/supabase-js) and needs
NEXT_PUBLIC_SUPABASE_URL plus either NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
(current Supabase projects and the Vercel/v0 integration) or the legacy
NEXT_PUBLIC_SUPABASE_ANON_KEY. npx atune init warns when one is missing.
Escape hatch: custom auth
Using an auth system Atune can't auto-detect? Provide the account explicitly. The rule of thumb: return the account this request belongs to — not just the logged-in user.
What is your account?
If you're unsure what your "account" is, ask: what would you bill this customer as one unit? That's the account.
For per-route named events with a custom account accessor, see Track named events.
Ask a grounded question POST
Answers a question about an account, user, feature, or portfolio from the workspace's existing signals. The endpoint returns `knows: false` instead of guessing when the bundle does not support an answer.
Any backend
Send events from Express, Hono, Fastify, Remix, workers, or a backend in any language.