Any website

Install npm install @blipit/browser

The Blipit browser SDK is 10 KB. It catches uncaught errors, unhandled promise rejections and failed requests, keeps the clicks and requests that led to each error, records web vitals, puts a Report a bug button on every page, and can record a session replay when an error happens. Install it from npm in a bundled app, or drop one script tag into any page.

Paste it into Claude Code, Cursor or any AI coding assistant. It carries the steps and the code. In app.blipit.io, API keys, the same prompt comes with your key filled in.
Video: Install Blipit in any stack, from 0:32

1Get your keys

Sign in at app.blipit.io and open API keys in the sidebar, then your project. Every project has two keys. The public key starts with blipit_pk_: it goes in browser and app code, can only send events, and is safe for anyone to see. The secret key starts with blipit_sk_: it stays on your server or in Odoo, never in a browser, because it can also read and change issues. The secret key is shown only once, right after it is created, so copy it then; if you lose it, press Create a new secret key, and the old one stops working at once. Some SDKs also need the project id, shown on the same page.

API keys in app.blipit.io: the public key (blipit_pk_) for browser code and the secret key (blipit_sk_) for servers and Odoo.
API keys in app.blipit.io: the public key (blipit_pk_) for browser code and the secret key (blipit_sk_) for servers and Odoo.
A new secret key is shown once. Copy it now: it is stored hashed and cannot be shown again.
A new secret key is shown once. Copy it now: it is stored hashed and cannot be shown again.

2With npm

Call init once in your entry file, before the app renders, with the public key. With Vite (React, Vue, Svelte), keep the key in .env as VITE_BLIPIT_KEY; only VITE_ variables reach the browser, and the dev server reads .env only when it starts.

sh
npm install @blipit/browser
.env
VITE_BLIPIT_KEY=blipit_pk_your_public_key
src/main.js
import * as Blipit from "@blipit/browser";

Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  environment: import.meta.env.MODE,
  release: "2026.09.28",
  replay: { onErrorSampleRate: 1 },
});

3Without a bundler: one script tag

Paste this into the <head> of every page, or into your platform's custom code slot, with your public key written in. That is fine: the public key can only send events.

html
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
  Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>

4Keep keys out of git

Keep keys in environment variables or your host's secret settings, never in code you commit, and add your .env files to .gitignore. A public key in a web page is normal. If a secret key ever ends up in git, a public page, a screenshot or a chat, open API keys, press Create a new secret key, and paste the new key wherever the old one was used: the old key stops working straight away.

.gitignore
.env
.env.local
.env.*.local

5Tell Blipit who the user is (optional)

After sign-in, attach the user so issues show who was affected and replays can be found by user.

js
Blipit.setUser({ id: "42", email: "ana@example.com" });

6React, Vue, Angular and Svelte: report caught errors

Frameworks catch errors inside components before the browser sees them, so pass those to Blipit too. Uncaught errors anywhere else are reported on their own.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
Or, React 18 and older: an error boundary
class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  componentDidCatch(error: Error) {
    Blipit.captureException(error);
  }
  render() {
    return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
  }
}
Vue (src/main.ts)
const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");
Angular (app.config.ts)
import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";

class BlipitErrorHandler implements ErrorHandler {
  handleError(error: unknown) {
    Blipit.captureException(error);
    console.error(error);
  }
}

export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };
SvelteKit (src/hooks.client.ts)
import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";

export const handleError: HandleClientError = ({ error }) => {
  Blipit.captureException(error);
};

7Bug reports: the Report a bug button

As soon as the SDK starts with your public key, a Report a bug button appears in the bottom-right corner of every page, in the visitor's language. A click opens the reporter: a screenshot of the page to mark up, an element picker, an optional screen recording, and a title and description. Change the position, style, text, colour and keyboard shortcut in code, as below, or for every site at once in app.blipit.io, Project settings, Bug report widget; options in code win. The Bug report button guide shows every option with screenshots and a live demo.

js
Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});
The default Report a bug button, bottom right.
The default Report a bug button, bottom right.
The reporter: a marked-up screenshot, the title and what happened.
The reporter: a marked-up screenshot, the title and what happened.

8Open the reporter from your own button

To put a Report a bug button in your own header or menu, use the official one: Blipit.reportButton() returns a ready-made button with the Blipit icon and Report a bug in the visitor's language, and React apps can render <BlipitReportButton /> from @blipit/nextjs/react (npm install @blipit/nextjs). Prefer your own design? Call openReport() from any click handler, or attachReport(element) to wire up an element that already exists. Either way the reporter opens exactly as it does from the floating button. The Blipit icon may only be used next to Report a bug, as the official button shows.

Official button, plain HTML
<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>
Official button, React
import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
Official button, Vue
<script setup>
import { onMounted, ref } from "vue";
import { reportButton } from "@blipit/browser";

const slot = ref();
onMounted(() => slot.value.append(reportButton({ variant: "outline", size: "sm" })));
</script>

<template>
  <span ref="slot"></span>
</template>
Plain HTML
<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>
React
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
Vue
<script setup>
import { openReport } from "@blipit/browser";
</script>

<template>
  <button @click="openReport()">Report Issue</button>
</template>
The official Report a bug button in a site header.
The official Report a bug button in a site header.
A custom Report Issue button in the page header opens the Blipit reporter.
A custom Report Issue button in the page header opens the Blipit reporter.

9Hide the default button

To keep only your own button, turn the floating one off with feedbackWidget: false in code (feedbackWidget={false} on <Blipit />), or switch off Show the bug report button in the project's Bug report widget settings to hide it on every site that uses the key. openReport() and attachReport() keep working either way.

js
Blipit.init({ key: import.meta.env.VITE_BLIPIT_KEY, feedbackWidget: false });

10Prefill the reporter and add context

Call setUser after sign-in: the reporter's name and email are filled in, and they get an email when you reply or change the status. setReportMetadata adds your own fields, such as the plan or the cart size, to every report; it runs when a report is sent, so the values are current.

js
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });

Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));

11All options and functions

  • key: the public key (blipit_pk_). Required.
  • environment and release: shown on every event; release powers regressions and source maps. environment defaults to production.
  • debug: true logs what the SDK does to the console, with lines that start with [blipit].
  • sampleRate (0 to 1), ignoreErrors (strings or patterns) and beforeSend (edit an event, or return null to drop it) control what is sent. autoMuteExtensions (on by default) drops errors that come only from browser extensions.
  • webVitals (on by default), replay ({ sessionSampleRate, onErrorSampleRate }) and autoSessionTracking (crash-free rates, needs release).
  • feedbackWidget: false hides the Report a bug button, or an object with position, style, text, color, font, match and shortcut changes it. theme: "light", "dark" or "auto" sets the reporter's theme.
  • user ({ id, name, email }) and company (a name or { id, name }) fill in the reporter and are added to reports.
  • endpoint: only for a self-hosted ingest; the default is https://in.blipit.io/api/v1/events.
  • Functions: captureException(error), captureMessage(text, level), setUser, setTag(key, value), addBreadcrumb({ category, message }), openReport(), attachReport(element), reportButton(options), updateWidget(options), setReportMetadata(fn), showFeedback() and flush(), which returns a promise once queued events are sent.
  • Widget settings changed in the dashboard reach browsers within an hour, because the SDK keeps them that long; a private window shows the change at once.

12Check it works

Reload your site. The Report a bug button appears in the bottom-right corner, and within a minute the page view shows under Web vitals in app.blipit.io. Then send a test event: call captureMessage once from your code, or with the script tag run the line below in the browser console. It shows under Issues within a few seconds.

js
Blipit.captureMessage("Hello from " + location.host, "info");

13If the button or the events do not show up

  • Open the browser console and look for lines that start with [blipit]. Turn on debug (debug: true in init, or debug on <Blipit />) to see whether the button was shown, turned off in code or hidden by the project setting.
  • Next.js only sends variables whose names start with NEXT_PUBLIC_ to the browser, so use NEXT_PUBLIC_BLIPIT_KEY. Vite only sends VITE_ variables, so use VITE_BLIPIT_KEY. With any other name the key is empty in the browser and Blipit does not start.
  • Restart the dev server after you add or change .env or .env.local. It reads them only when it starts.
  • On Vercel or any other host, add the same variable in the project's environment variables and deploy again. NEXT_PUBLIC_ and VITE_ values are written into the build, so a running deployment never sees a value added later.
  • Use the public key (blipit_pk_). A secret key (blipit_sk_) is refused in the browser with a console error; if one was ever on a page, create a new secret key.
  • In Next.js, <Blipit /> belongs in the root app/layout.tsx (or pages/_app.tsx) so it runs on every page. In other apps, call init once in the entry file, before the app renders.
  • Show the bug report button must be on in app.blipit.io, Project settings, Bug report widget, and your code must not pass feedbackWidget: false. The SDK keeps the project settings for up to an hour, so test a change in a private window.
  • Ad blockers and privacy extensions can block in.blipit.io. Try a private window with extensions turned off.
  • If your site sends a Content Security Policy, allow script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: and media-src blob:. The reporter editor loads from blipit.io/sdk on the first click, the screenshot is drawn from a data: image, and screen recordings upload to in.blipit.io too. With debug on, the console says when the policy blocked the screenshot. For voice in screen recordings, the site's Permissions-Policy header must allow microphone=(self), and display-capture=(self) for screen recording; with microphone=() recordings work without sound.
  • Check which version is installed with npm ls @blipit/browser @blipit/nextjs (or pnpm list @blipit/browser @blipit/nextjs) and compare it with the changelog. pnpm 11 waits a day before it installs a new release (minimum-release-age), so on release day pnpm add quietly installs the previous version. To get the new one at once: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Still stuck? Email support@blipit.io with the [blipit] lines from the console.

Good to know

  • Options: sampleRate (0 to 1), ignoreErrors (strings or patterns), beforeSend to drop or edit an event, maxBreadcrumbs, webVitals (on by default), autoSessionTracking for crash-free rates (needs release).
  • blipit.io/sdk/blipit.js always serves the latest version (0.3.23). Pinned versions live at blipit.io/sdk/0.3.23/blipit.js if you want to control upgrades.
  • If your site sends a Content Security Policy, allow script-src https://blipit.io (the script tag, and the reporter editor and replay add-on, which load from blipit.io/sdk/<version>/ on first use), connect-src https://in.blipit.io (events, screenshots and screen recordings all go to in.blipit.io), img-src data: (the screenshot is drawn from an image of the page) and media-src blob: (recordings play back in the reporter). The screenshot reloads the page's images and fonts, so their hosts belong in connect-src too, or they are left blank. No style-src change is needed. With the script tag, call Blipit.init from your own .js file or give the inline script a nonce, because a strict policy blocks inline scripts. For voice in screen recordings, the site's Permissions-Policy header must allow microphone=(self), and display-capture=(self) for screen recording; with microphone=() recordings work without sound.
  • Keeping Blipit up to date: the Keeping Blipit up to date guide (docs.blipit.io/updates) explains the update banner, the emails for important releases, the notice in your development console and the update command for this platform.
  • One project per app and platform: each project picks its platform when it is created (Android, iOS, React Native, Flutter, Web, Backend or Odoo), and Blipit refuses data from any other platform with a clear error, so an iOS app and an Android app need two projects with two keys. Releases, versions, crash rates and store builds differ per platform, so mixing them in one project makes all of them wrong. A Web project also takes the server side of the same web app (the Next.js server or Node), and a React Native or Flutter project also takes its own native Android and iOS crash reports.

Stuck? Email support@blipit.io. Keys and the project id for each project are under API keys in app.blipit.io.