Install Vaka in a web app (JavaScript)

Project: your-project · Endpoint: https://vaka.example.com · Ingest key: vk_your_ingest_key

These steps are written to be followed by a coding agent. Do them in order and verify at the end.

1. Pick an install method

Option A: script tag (static sites, server-rendered apps, anything without a bundler). Add this to every page's <head>:

<script defer src="https://vaka.example.com/sdk/vaka.js"
        data-key="vk_your_ingest_key"
        data-release="REPLACE_WITH_APP_VERSION"></script>

Optional attributes: data-environment="production", data-hash="true" (hash routing), data-pageviews="false", data-errors="false", data-ignore-localhost="true", data-debug="true". The global window.Vaka exposes the same API as the npm package.

Option B: npm package (apps built with Vite, webpack, Next.js, etc.).

npm install vaka-browser

Initialise once, as early as possible in the client entry point (e.g. main.ts):

import * as Vaka from 'vaka-browser';

Vaka.init({
  key: 'vk_your_ingest_key',
  endpoint: 'https://vaka.example.com',
  release: import.meta.env.VITE_APP_VERSION, // any string; must match the source map upload
  environment: import.meta.env.MODE,
});

For server-side rendering frameworks, call init only in the browser (typeof window !== 'undefined').

2. What you get automatically

Uncaught errors and unhandled promise rejections, with breadcrumbs (clicks, navigation, console warnings/errors, failed fetch).
Cookieless pageviews, including SPA navigation (history.pushState/popstate).
A session per page load, so crash-free rates per release work.

3. Optional calls

Vaka.track('signup', { plan: 'pro' });     // custom event (props: string/number/boolean)
Vaka.captureError(err, { tags: { area: 'checkout' } });  // handled error
Vaka.captureMessage('Payment provider slow', 'warning');
Vaka.addBreadcrumb({ category: 'cart', message: 'Added item 42' });
Vaka.setTag('tenant', 'acme');
Vaka.identify('user-123');                 // opt-in only; Vaka.identify(null) clears it

Do not call identify with emails or names unless the app's privacy policy allows it.

4. Upload source maps (production builds)

Generate source maps in the build (Vite: build.sourcemap: true; webpack: devtool: 'source-map'), then upload them after each build with the vaka CLI using an API token with write access:

export VAKA_URL=https://vaka.example.com VAKA_TOKEN=vt_... VAKA_PROJECT=your-project
vaka upload sourcemaps dist --release "$APP_VERSION" --url-prefix /assets

--url-prefix is the URL path the minified files are served from. --release must equal the release passed to init. You may delete the .map files from the deployed output afterwards.

5. Verify

Load the app in a browser and run Vaka.captureMessage('vaka install test') in the console (script tag) or trigger a test error.
Check with the API: curl -H "Authorization: Bearer $VAKA_TOKEN" https://vaka.example.com/api/v1/projects/your-project/issues, or the MCP tool list_issues. The event appears within a few seconds.
Pageviews appear in analytics_summary / GET /api/v1/projects/your-project/analytics/summary.

If nothing arrives: enable debug: true, check the browser network tab for /ingest/v1/batch (expect 202), and make sure a Content-Security-Policy allows connect-src https://vaka.example.com (and script-src for option A).