Installation & setup

Requirements#

• A browser app built with a bundler (Vite, webpack, Next.js, Rollup, esbuild…).
• A public ingest key (cs_…_pk_…) from an active Codeskop plan.

The package ships as both ES modules and CommonJS, with TypeScript types included. It has no runtime dependencies and is tree-shakeable.

Install#

npm install @codeskop/tracker

yarn add @codeskop/tracker

pnpm add @codeskop/tracker

It's a public, MIT-licensed package, no npm token or .npmrc entry needed. You can install and try it without an account; it only starts sending data once it has a valid key.

Initialize#

Call init once, as early as possible in your entry file, so errors thrown while your app boots are captured too.

1import { init } from "@codeskop/tracker";2 3init({4  apiKey: import.meta.env.VITE_CODESKOP_KEY, // cs_live_pk_…5  release: import.meta.env.VITE_APP_VERSION,6});

From this point on, the SDK automatically captures:

• uncaught errors and unhandled promise rejections,
• failed fetch and XMLHttpRequest calls (network errors and HTTP 4xx/5xx),
• the timing of every request,
• a presence heartbeat while the tab is visible.

init returns immediately; queue setup, the config fetch and sending all happen in the background. Requests to Codeskop itself are never captured.

Use a test key outside production

Keep development traffic out of your production data by switching keys per build:

1init({2  apiKey: import.meta.env.PROD3    ? "cs_live_pk_YOUR_LIVE_KEY"4    : "cs_test_pk_YOUR_TEST_KEY",5});

Identify users#

1import { identify, reset } from "@codeskop/tracker";2 3onLogin((user) => identify(user.id));4onLogout(() => reset());

Use your own stable user ID, never an email address. Until you call identify, events are attributed to an anonymous ID stored in localStorage (or a cookie if storage is unavailable).

Report handled errors#

Errors you catch yourself never reach the global handlers. Report the ones you care about with recordException:

1import { recordException } from "@codeskop/tracker";2 3try {4  await checkout(cart);5} catch (error) {6  recordException(error);7  showCheckoutError();8}

Handled exceptions are always kept and never sampled away.

Let users opt out#

1import { setEnabled } from "@codeskop/tracker";2 3// e.g. when a user turns off diagnostics in your settings screen4setEnabled(false);

setEnabled(false) pauses all capture until you call setEnabled(true). It lasts for the current page session. Call it again after init on the next load if the user's choice should persist.

Server-side rendering#

The SDK only does browser work, and every function is safe to import on the server. In Next.js, Remix and similar frameworks, call init from client-only code. For React apps, the React provider handles this for you.

Next steps