Docs▸Browser SDK

Source maps

Production scripts are minified, so a raw stack trace points at minified code. Upload your source maps when you build, and Vigilon shows each frame at its original file, line, and function, with a few lines of your source around it.

How it works

At the end of a production build, the Vigilon bundler plugin gives every script one debug ID, a UUID it writes into the script and into its source map, and uploads both. The browser SDK sends the debug IDs of the scripts in an error's stack with the error, so Vigilon finds the right source map whatever the file is called and wherever it is served from. Your source maps never need to be public.

A build that already injects debug IDs for Sentry needs no second pass: the plugin reuses a debug ID it finds, and the SDK reads Sentry's registry too. Plugin order does not matter.

Create an upload token

Open your project's Settings page, then the Source Maps tab, and create an upload token. It starts with vg_sm_ and is shown once. Set it as VIGILON_SOURCE_MAP_TOKEN where your production build runs, for example as a CI secret.

Keep it secret

Never put the upload token in client code or in a variable your bundler exposes to the browser, such as VITE_ or NEXT_PUBLIC_: anyone with it can replace your project's source maps. An API key does not work here.

Vite

Install the plugin as a development dependency. It needs Node.js 22.12 or later.

shell
npm install --save-dev @vigilon/bundler-plugins
vite.config.ts
import { defineConfig } from "vite";
import vigilon from "@vigilon/bundler-plugins/vite";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [vigilon({ uploadToken: process.env.VIGILON_SOURCE_MAP_TOKEN })],
});

sourcemap: "hidden" builds source maps without a sourceMappingURL comment, so browsers never ask for them. The plugin reads VIGILON_SOURCE_MAP_TOKEN by itself; passing uploadToken just makes it explicit.

webpack

webpack.config.js
const vigilon = require("@vigilon/bundler-plugins/webpack").default;

module.exports = {
  mode: "production",
  devtool: "hidden-source-map",
  plugins: [vigilon()],
};

Rollup and esbuild

rollup.config.mjs
import vigilon from "@vigilon/bundler-plugins/rollup";

export default {
  input: "src/main.js",
  output: { dir: "dist", format: "es", sourcemap: "hidden" },
  plugins: [vigilon()],
};
build.mjs
import { build } from "esbuild";
import vigilon from "@vigilon/bundler-plugins/esbuild";

await build({
  entryPoints: ["src/main.js"],
  bundle: true,
  outdir: "dist",
  sourcemap: "external",
  plugins: [vigilon()],
});

What happens to your maps

If your build produces no source maps, the plugin turns on hidden source maps and deletes them after the upload, so none is deployed. If it already produces maps, they stay where they are unless you set deleteSourceMapsAfterUpload: true. Inline source maps cannot be uploaded. Development builds and Vite server-side builds are skipped.

A failed upload, or a script Vigilon reports as unusable, fails the build. Pass onUploadError: "warn" to log a warning instead. Without a token the plugin still writes debug IDs and uploads nothing.

Other build tools

For any other build, run @vigilon/cli on the build output, after the build and before you deploy:

shell
npx @vigilon/cli sourcemaps inject dist
npx @vigilon/cli sourcemaps upload dist --delete-after-upload

inject gives every script that has a source map a debug ID, in place, so run it on files that are not deployed yet. upload reads VIGILON_SOURCE_MAP_TOKEN and exits with status 1 when the upload fails or Vigilon cannot use a script; add --warn-only to carry on instead.

Check your uploads

The Source Maps tab lists the uploaded source maps, and why Vigilon rejected any it could not use. An error from a script whose map is missing or rejected keeps its minified frames.

Vigilon waits a few minutes for a source map that has not arrived yet, so deploy once the upload has finished. An error stored before its map arrived keeps its minified frames.