Install

With a bundler

npm install @tailcove/browser

With a plain <script> tag (no build step)

<script src="https://unpkg.com/@tailcove/browser/dist/tailcove.umd.global.js"></script>

Quick start

1. Get a browser key. In your Tailcove dashboard, open your source's Settings tab and create a browser key. Add the websites that may use it under allowed origins.

A browser key is meant to be public. It ships in your front-end code, so don't treat it like a password. Access is controlled by the allowed origins you set. This is different from the server-side ingest token used by @tailcove/node, which must stay secret.

2. Send your first log.

import { init } from '@tailcove/browser';

const tailcove = init({ key: 'your-browser-key' });

tailcove.error('checkout failed', { orderId: 99 });

With the script tag, the same code looks like this:

<script>
  const tailcove = Tailcove.init({ key: 'your-browser-key' });
  tailcove.error('checkout failed');
</script>

3. Open Tailcove. Your lines appear in search and live tail within a couple of seconds.

Level helpers are debug, info, notice, warning (with warn as a console-style alias), error, critical, alert and emergency. You can also call log(level, message, context) directly.

Catch errors automatically

Nothing is captured until you ask for it. A client that records everything by default is a noisy one, so each switch is off to begin with:

const tailcove = init({
    key: 'your-browser-key',
    captureWindowErrors: true,        // uncaught errors (window.onerror)
    captureUnhandledRejections: true, // unhandled promise rejections
    captureConsoleErrors: true,       // console.error(...) calls
    consoleSampleRate: 0.1,           // keep 10% of console.error calls
});

Captured errors use the same structured shape as every Tailcove client (class, message, location, trace). A browser TypeError therefore groups into the same issue as a matching error from your server.

location comes from the first stack frame, so it is only meaningful for unminified builds. Source map support is not included yet.

Options

| Option | Default | What it does | |---|---|---| | key | — | Your source's browser key. Required. | | endpoint | https://ingest.tailcove.dev/api/v1/browser/logs | The ingest URL. Only change this if you self-host. | | batchSize | 20 | Send once this many lines are buffered. | | batchIntervalMs | 2000 | Send once this many milliseconds have passed since the first buffered line. | | timeoutMs | 2000 | How long a delivery attempt may take before giving up. | | context | {} | Fields added to every line. Per-call context wins if keys clash. | | enabled | true | Set false to turn the client off. Nothing is buffered or sent. | | onError | — | Called with the error when a batch fails to send. Without it, failures are dropped silently. | | captureWindowErrors | false | Capture uncaught errors. | | captureUnhandledRejections | false | Capture unhandled promise rejections. | | captureConsoleErrors | false | Capture console.error(...) calls. | | consoleSampleRate | 1 | Fraction of console.error calls kept when captureConsoleErrors is on. | | traceLimit | 10 | Stack frames kept for each captured error. |

What gets added automatically

| Field | Value | |---|---| | url | window.location.href | | userAgent | navigator.userAgent | | viewport | { width, height } |

Add your own fields to every line with the context option, for example userId or plan.

Frameworks

React

import { ErrorBoundary, TailcoveProvider } from '@tailcove/browser/react';

function App() {
    return (
        <TailcoveProvider options={{ key: 'your-browser-key' }}>
            <ErrorBoundary fallback={<p>Something went wrong.</p>}>
                <YourApp />
            </ErrorBoundary>
        </TailcoveProvider>
    );
}

ErrorBoundary also takes an explicit client prop, and fallback can be a function, (error) => ..., if you want to show the error.

Vue

import { createApp } from 'vue';
import TailcovePlugin from '@tailcove/browser/vue';

const app = createApp(App);
app.use(TailcovePlugin, { key: 'your-browser-key' });

The plugin hooks app.config.errorHandler and chains any handler you already registered.

Svelte (SvelteKit)

// src/hooks.client.ts
import { createTailcoveHandleError } from '@tailcove/browser/svelte';

export const handleError = createTailcoveHandleError({ key: 'your-browser-key' });

Next.js

// instrumentation-client.ts
import { init } from '@tailcove/browser/nextjs';

export const tailcove = init({ key: 'your-browser-key' });

// app/global-error.tsx
'use client';
import { useEffect } from 'react';
import { reportGlobalError } from '@tailcove/browser/nextjs';
import { tailcove } from '../instrumentation-client';

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
    useEffect(() => reportGlobalError(tailcove, error), [error]);

    return (
        <html>
            <body>Something went wrong.</body>
        </html>
    );
}

@tailcove/browser/nextjs runs in the browser only. A full-stack Next.js app wants this package for the browser bundle and @tailcove/node for route handlers, server components and middleware.

How delivery works

Normal calls are batched and sent with fetch. When the tab is hidden or the page is leaving (visibilitychange to hidden, or pagehide), the client flushes with navigator.sendBeacon instead, because a request already in flight or a timer that has not fired can be cut off while the page unloads, but a beacon is not. If sendBeacon is unavailable or rejects the payload, it falls back to fetch with keepalive: true.

Several clients on one page share a single set of unload listeners. To remove a client early, for example when a framework adapter unmounts, call client.destroy(). It flushes first, then detaches.

Network errors and non-2xx responses never throw into your page. They go to onError if you set one, and are dropped otherwise.

Help and feedback

• Docs: tailcove.dev/docs/sending-logs/browser
• Bugs and feature requests: open an issue
• Security problems: please email [email protected] instead of opening a public issue.