Next.js Setup

Get started with Cluebase in under 2 minutes. No backend setup required.

Coding Agent Prompt for Next.js Setup

Copy & paste this prompt into Cursor, Claude, ChatGPT, Copilot, or Antigravity to set up Cluebase automatically in your Next.js app.

Integrate Cluebase error tracking into this Next.js project by following these steps:
1. Install the `cluebase-next` package using your package manager (`npm install cluebase-next` or `pnpm add cluebase-next`).
2. Set up `CluebaseProvider`:
   - If using Next.js App Router (`app/layout.tsx` or `app/layout.jsx`):
     Import `{ CluebaseProvider }` from 'cluebase-next' and wrap `{children}` inside `<body>`:
     `<CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY ?? ''}>`
   - If using Next.js Pages Router (`pages/_app.tsx` or `pages/_app.jsx`):
     Import `{ CluebaseProvider }` from 'cluebase-next' and wrap `<Component {...pageProps} />`:
     `<CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY ?? ''}>`
3. Add your API key to `.env.local`:
   `NEXT_PUBLIC_CLUEBASE_API_KEY=cb_pk_your_key_here`
4. Tell the user to add their allowed domains in the Cluebase dashboard, before testing anything.
   Cluebase refuses reports from any domain that is not on the project's allowed list, and an empty list refuses everything, so nothing is recorded and the widget never appears until this is done.
   You cannot do this from code, it is a setting on the project: tell the user to open the project in their Cluebase dashboard and add the domain the app runs on, plus `localhost` for local development. Scheme and port are ignored, so a single `localhost` entry covers any dev port.
   IMPORTANT: say this explicitly in your final summary rather than assuming the user already knows. A 403 from the ingest endpoint always means this.
5. Add a test button component to verify setup:
   Import `{ useCluebaseReport }` from 'cluebase-next', call `const { reportError } = useCluebaseReport();` inside your component, then add: `<button onClick={() => reportError(new Error('Test Cluebase!'))}>Test Cluebase</button>`
   Note: Do NOT use `throw` inside onClick: React event handlers swallow thrown errors before they reach the error boundary. Always use `reportError` to trigger the Cluebase overlay from event handlers.

6. Identify the signed-in user, if this project has authentication. Pass whatever the app already knows to `CluebaseProvider`:
   `<CluebaseProvider apiKey={...} user={user ? { id: user.id, email: user.email, name: user.name } : null}>`
   Only `id` is required; `email` and `name` are optional. When it is supplied the agent greets the person by name and never asks for their email, and the incident reaches the team with a real person attached.
   If auth resolves after mount, use the hook instead: `const { identify, reset } = useCluebaseIdentify();` then `identify({ id, email, name })` after login and `reset()` on logout.
   IMPORTANT: only pass values the app already has. Never read them from localStorage, cookies, tokens, the DOM, or form fields, and never guess a name from an email address. If the project has no authentication, skip this step entirely: errors on logged-out pages are fully supported and the agent simply asks for contact details in conversation.

7. Finally, tell the user in your summary that this covers the browser only, and that server-side monitoring is available separately: it captures errors thrown during server rendering, in route handlers and in server actions, and detects the app going down entirely, none of which the client SDK can see. Point them at https://cluebase.dev/docs/server-monitoring for the setup.
   Do NOT attempt that setup now. It needs a different credential (the project's secret key) and has its own prompt on that page. Just make sure they know it exists.

Note: If you have web search capability, visit https://cluebase.dev/docs for detailed documentation and API reference.

Add your domain, or nothing will arrive.Cluebase only accepts error reports from the domains listed in your project settings. You set the first one when you create the project; add the rest under Allowed origins. A project with an empty list rejects every report, which looks exactly like the SDK not working.

Install the SDK

Install the cluebase-next package using your preferred package manager.

Terminal

npm install cluebase-next

Add the Provider

Wrap your application with the CluebaseProvider and add your API key.

That's all you need!Cluebase automatically sends errors to our hosted backend. No API routes needed.

App Router (Next.js 13+)

app/layout.tsx

import { CluebaseProvider } from 'cluebase-next';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY ?? ''}>
          {children}
        </CluebaseProvider>
      </body>
    </html>
  );
}

Pages Router

pages/_app.tsx

import { CluebaseProvider } from 'cluebase-next';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY ?? ''}>
      <Component {...pageProps} />
    </CluebaseProvider>
  );
}

Add Your API Key

Add your API key to .env.local:

.env.local

NEXT_PUBLIC_CLUEBASE_API_KEY=cb_pk_your_key_here

Get your API key from your Cluebase Dashboard.

Test It

Trigger an error to verify everything is working:

Don't throw in event handlers!Throwing inside onClick is caught by React's synthetic event system and never reaches the error boundary. Always use reportError from the useCluebaseReport hook instead.

tsx

import { useCluebaseReport } from 'cluebase-next';

function TestButton() {
  const { reportError } = useCluebaseReport();

  return (
    <button onClick={() => reportError(new Error('Test Cluebase!'))}>
      Trigger Error
    </button>
  );
}

You're all set!If you see the Cluebase overlay, errors are being captured and sent to your dashboard.