React

Install#

Install the React adapter alongside the core package:

npm install @codeskop/tracker @codeskop/tracker-react

yarn add @codeskop/tracker @codeskop/tracker-react

pnpm add @codeskop/tracker @codeskop/tracker-react

react ^18.0.0 || ^19.0.0 is a peer dependency. The core package stays framework-free; only this adapter depends on React.

Set up the provider and boundary#

Wrap your app once, at the root:

1import { createRoot } from "react-dom/client";2import { CodeskopProvider, CodeskopErrorBoundary } from "@codeskop/tracker-react";3 4createRoot(document.getElementById("root")!).render(5  <CodeskopProvider config={{ apiKey: "cs_live_pk_YOUR_KEY", release: "1.4.0" }}>6    <CodeskopErrorBoundary fallback={<p>Something went wrong.</p>}>7      <App />8    </CodeskopErrorBoundary>9  </CodeskopProvider>,10);

• CodeskopProvider calls init(config) once, when it mounts.
• CodeskopErrorBoundary catches errors thrown while rendering its children, reports them, and shows fallback instead of a blank screen.

Error boundary options#

1<CodeskopErrorBoundary2  fallback={(error, reset) => (3    <div role="alert">4      <p>This section failed to load.</p>5      <button onClick={reset}>Try again</button>6    </div>7  )}8  onError={(error, info) => console.error(error, info.componentStack)}9>10  <Dashboard />11</CodeskopErrorBoundary>

You can nest boundaries: wrap individual widgets so one failing panel doesn't take down the whole page.

The useCodeskop hook#

useCodeskop() returns identify, reset, recordException, setEnabled and flush, the same functions the core package exports.

1import { useEffect } from "react";2import { useCodeskop } from "@codeskop/tracker-react";3 4function Profile({ user }: { user: User }) {5  const { identify, recordException } = useCodeskop();6 7  useEffect(() => {8    identify(user.id);9  }, [user.id, identify]);10 11  async function save() {12    try {13      await saveProfile(user);14    } catch (error) {15      recordException(error); // event handlers aren't covered by error boundaries16    }17  }18 19  return <button onClick={save}>Save</button>;20}

The hook works anywhere, even outside a CodeskopProvider: every function is a safe no-op until the SDK is initialized.

The provider starts the SDK during its first render, before any child's effects run, so calling identify from a child's first useEffect works (from version 1.1).

What boundaries don't catch#

This is a React limitation, not a Codeskop one: error boundaries only catch errors thrown during render. They don't see errors from:

• event handlers such as onClick,
• useEffect callbacks and other async code,
• server-side rendering.

Uncaught errors from event handlers and promises are still captured by the SDK's global handlers. For errors you catch yourself, call recordException.

Next.js and other SSR frameworks#

The provider is SSR-safe: it only starts the SDK in the browser, so nothing runs during server rendering and no typeof window checks are needed. The package ships a "use client" directive (from 1.1), so in the Next.js App Router you can use it straight from app/layout.tsx:

1// app/layout.tsx: works in a Server Component from 1.12import { CodeskopProvider, CodeskopErrorBoundary } from "@codeskop/tracker-react";3 4export default function RootLayout({ children }: { children: React.ReactNode }) {5  return (6    <html lang="en">7      <body>8        <CodeskopProvider config={{ apiKey: process.env.NEXT_PUBLIC_CODESKOP_KEY! }}>9          <CodeskopErrorBoundary fallback={<p>Something went wrong.</p>}>{children}</CodeskopErrorBoundary>10        </CodeskopProvider>11      </body>12    </html>13  );14}

Identifying signed-in users, reporting your app version from package.json, and fixes for common errors are in Web configuration.

Environment variables

Your bundler has to expose the key to browser code, for example NEXT_PUBLIC_ in Next.js or VITE_ in Vite. That's fine: public ingest keys are designed to be visible.

Next steps