Next.js Quickstart
From zero to tracking in 5 minutes with Next.js App Router
Next.js Quickstart
Get Thisbefine tracking events in your Next.js app in 5 minutes.
Install the SDK
pnpm add @thisbefine/analyticsAdd the Analytics Component
Drop the <Analytics /> component into your root layout:
import { Analytics } from '@thisbefine/analytics/next';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<Analytics
apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!}
debug={process.env.NODE_ENV === 'development'}
/>
</body>
</html>
);
}That's your entire analytics setup. Pageviews are tracked automatically.
Track Your First Event
Use the useTrack hook to track custom events:
'use client';
import { useTrack } from '@thisbefine/analytics/next';
export const SignupButton = () => {
const trackSignup = useTrack('signup_clicked');
return (
<button onClick={() => trackSignup({ source: 'hero_section' })}>
Sign Up Free
</button>
);
};Identify Users
When someone logs in, tell us who they are:
'use client';
import { useIdentify } from '@thisbefine/analytics/next';
export default function LoginPage() {
const identify = useIdentify();
const handleLogin = async (email: string, password: string) => {
const user = await login(email, password);
identify(user.id, {
email: user.email,
name: user.name,
plan: user.plan,
});
};
return <form>{/* your form */}</form>;
}Previous anonymous activity gets linked to this user automatically.
Check Your Dashboard
Head to your Thisbefine dashboard. Events should start appearing.
Debug Mode: With debug: true, events are logged to the browser console. Open DevTools and watch them roll in.
Zero Config Option
Set the environment variable and skip the apiKey prop entirely:
NEXT_PUBLIC_TBF_API_KEY=tif_your_api_key<Analytics />The component reads from NEXT_PUBLIC_TBF_API_KEY automatically.
What's Automatic?
Once you add the <Analytics /> component:
| Feature | What It Does |
|---|---|
| Pageviews | Every route change tracked via usePathname |
| Sessions | New session after 30 min of inactivity |
| Anonymous IDs | Every visitor gets a unique ID |
| Context | Browser, screen size, locale - all captured |
Enable Error Tracking
Catch JavaScript errors automatically:
<Analytics
apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!}
config={{
errors: {
enabled: true,
captureConsoleErrors: true,
maxBreadcrumbs: 25,
},
}}
/>Now when things break, you'll know about it before your users email you.
Add the Bug Report Button
Let users report bugs with one line:
import { Analytics, BugReportFAB } from '@thisbefine/analytics/next';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
{children}
<Analytics apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!} />
<BugReportFAB position="bottom-right" />
</body>
</html>
);
}Users click it, fill out a form, maybe attach a screenshot. You get the report with full context.
Common Patterns
Reset on Logout
Always reset when users log out to avoid mixing user data:
'use client';
import { useReset } from '@thisbefine/analytics/next';
const LogoutButton = () => {
const reset = useReset();
const handleLogout = async () => {
await logout();
reset();
router.push('/login');
};
return <button onClick={handleLogout}>Logout</button>;
};Group Users by Workspace
For B2B apps with workspaces or teams:
import { useGroup } from '@thisbefine/analytics/next';
const group = useGroup();
group(workspace.id, {
name: workspace.name,
plan: workspace.plan,
memberCount: workspace.members.length,
});You're Done
You now have:
- Automatic pageview tracking
- Event tracking via
useTrack - User identification via
useIdentify - Error capture (if enabled)
- Bug reports (if added)