@browsonic/build-tools

Bundler plugins that upload your build's source maps to Browsonic, so the dashboard can symbolicate that release's stack traces on demand.

Apache-2.0. Part of the Browsonic SDK monorepo.

Status (2026-07-28)

Read this before trusting the rest of the file.

• npm latest for this package is 1.2.2, and it matches main. Published 2026-07-27 together with its pinned dependency @browsonic/cli 1.2.3. Everything below — Debug IDs above all — is available to anyone installing from npm. (1.2.0 was version-stamped but never published as a release of its own.)
• The client/server part-name mismatch on the upload path is fixed in the published versions. These plugins delegate to @browsonic/cli, which up to 1.2.1 posted the map under a multipart part named sourcemap while browsonic-service's POST /v1/sourcemaps binds file — so every real upload from a plugin version older than this one was rejected with 400. @browsonic/cli 1.2.3 (the version 1.2.1 of this package pins) posts file, docs/design/SOURCEMAP_PIPELINE.md documents that, and the part names are pinned by tests on both sides. The service also accepts sourcemap as a deprecated alias, so an already-installed older version works against a service carrying it. End-to-end upload against the live service is still UNVERIFIED (2026-07-28) — the contract now agrees on both sides and is test-pinned, but no one has run a real upload through it. Everything the plugins do locally — dist walk, release derivation, debugId stamping — is covered by tests and works.
• Source-map upload and symbolication are plan-gated (source_maps, Flyway V42): professional and enterprise only. Free and Starter tenants get 402 Payment Required from /v1/sourcemaps and /v1/symbolicate.

Why

Browsonic uploads source maps via @browsonic/cli (browsonic upload-sourcemaps). The CLI is fine in CI scripts, but most teams already have a bundler — Vite, Webpack, Rollup, or esbuild — running. This package wraps the CLI as a bundler plugin so the upload happens as part of npm run build. No extra CI step, and the release is derived in the same process that produced the artefacts.

The plugins add nothing to your bundle at runtime: they only fire after the build is written to disk. The one exception is debugIdInjection: true, which deliberately appends a small snippet to each bundle — see Debug IDs. Source-map upload is configured to never break the build by default — a missing BROWSONIC_SOURCEMAP_TOKEN or a transient ingest 5xx logs a warning and the build continues.

Install

npm install --save-dev @browsonic/build-tools

This installs 1.2.1 today — see Status.

The bundler itself is a peer dependency — install whichever one your project uses (vite, webpack, rollup, esbuild); all four are declared optional. The plugin's import path determines which bundler hook it targets, so you only get the code for what you actually use.

Vite

// vite.config.ts
import { defineConfig } from "vite";
import browsonicSourceMaps from "@browsonic/build-tools/vite";

export default defineConfig({
  build: { sourcemap: "hidden" }, // emit .map files without sourceMappingURL
  plugins: [browsonicSourceMaps({ appKey: "web" })],
});

build.sourcemap: 'hidden' is the recommended setting: production assets do not advertise the source maps to end users, but the .map files are still written to disk where the plugin picks them up.

Webpack

// webpack.config.js
import { BrowsonicSourceMapsPlugin } from "@browsonic/build-tools/webpack";

export default {
  devtool: "hidden-source-map",
  plugins: [new BrowsonicSourceMapsPlugin({ appKey: "web" })],
};

devtool: 'hidden-source-map' strips the sourceMappingURL comment from the bundle so the maps stay private.

Rollup

// rollup.config.js
import browsonicSourceMaps from "@browsonic/build-tools/rollup";

export default {
  output: { dir: "dist", sourcemap: "hidden" },
  plugins: [browsonicSourceMaps({ appKey: "web" })],
};

esbuild

import { build } from "esbuild";
import browsonicSourceMaps from "@browsonic/build-tools/esbuild";

await build({
  entryPoints: ["src/index.ts"],
  outdir: "dist",
  sourcemap: "external",
  plugins: [browsonicSourceMaps({ appKey: "web" })],
});

esbuild's plugin model fires onEnd after every build — in watch mode that means an upload per rebuild. Either skip the plugin in dev configs or pass dryRun: true.

Options

| Option | Type | Default | Description | | ------------------ | --------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | appKey | string | (required) | The application key from the Browsonic dashboard. | | release | string | env → git short-sha → package.json version | Release identifier. Falls back through that chain when omitted. | | token | string | BROWSONIC_SOURCEMAP_TOKEN | Bearer token. Minted per-app in the dashboard under Admin → Source Maps ("Upload tokens"); shown once at creation. | | baseUrl | string | BROWSONIC_API_ENDPOINT → api.browsonic.com | Ingest endpoint base URL. | | distPath | string | (auto-detected from bundler) | Override the dist directory. Useful when the bundler's default differs from where maps land. | | dist | string | (none) | Distribution discriminator. Posted on the wire by @browsonic/cli, but POST /v1/sourcemaps has no dist parameter and ignores it. | | dryRun | boolean | false | Walk + report without making the HTTP call. Handy for CI smoke tests. Also skips debugIdInjection (no artefact mutation). | | bailOnError | boolean | false | When true, throws on upload failure instead of warning. Also applies to release derivation and to a whole-run debugId injection failure — but not to per-file injection failures (see Debug IDs). | | silent | boolean | false | Suppress all stdout/stderr output from the plugin. Note this also silences the "token missing, skipping upload" warning. | | debugIdInjection | boolean | false | (1.2.1+) Stamp a debugId (UUID) into every bundle + sourcemap pair before upload — one fresh id per pair, not one per build. See Debug IDs. |

Environment variables

The plugin reads three env vars when the corresponding option is missing:

• BROWSONIC_SOURCEMAP_TOKEN — auth token. Without it, the plugin logs a warning and skips upload (build continues).
• BROWSONIC_RELEASE — release identifier. First in the fallback chain.
• BROWSONIC_API_ENDPOINT — ingest base URL. Defaults to https://api.browsonic.com.

Debug IDs

(1.2.1+, published 2026-07-27; see Status.)

Opt in with debugIdInjection: true and, right before the upload step, the plugin stamps a UUID into every bundle + external-sourcemap pair (foo.js + foo.js.map) it finds under the dist path. Each pair gets its own fresh id; there is no single per-build id.

• Bundle — a one-line snippet is appended to the end of the file (appending never shifts existing sourcemap line mappings). At runtime it registers the id on the shared global _browsonicDebugIds. The reader for that global lives in @browsonic/sdk (packages/sdk/src/utils/debug-ids.ts, added in the 3.20.0 tree and first published in 3.21.0): it attaches a debugIds field ({ scriptUrl: debugId }) to error events whose stack frames reference a stamped bundle. An SDK older than 3.21.0 does not read the global, so pair this with @browsonic/sdk >= 3.21.0. A trailing //# debugId=<uuid> comment makes the id greppable in the artefact.
• Sourcemap — a top-level "debugId": "<uuid>" property is added to the .map JSON.

CLI-flow compatibility. Injection does not change the upload wire contract: maps are still keyed by (appKey, release, filename) and @browsonic/cli posts the .map content verbatim — the id simply travels inside the uploaded file. So stamped maps can be uploaded by this plugin or by a later separate browsonic upload-sourcemaps run (injection happens even when BROWSONIC_SOURCEMAP_TOKEN is missing and the upload itself is skipped).

What Browsonic's own backend does with the id today: nothing. browsonic-service records a debugId only when the uploader sends an explicit multipart debugId field (SourceMapController#upload → sourcemap_uploads.debug_id); @browsonic/cli does not send that field, and nothing server-side parses the id out of the uploaded .map body. /v1/symbolicate resolves frames by (tenantId, appKey, release, filename), and the SDK's debugIds event field has no counterpart in the ingest DTOs. Until that changes, injection is a build-side artefact-stamping feature only — useful for grepping which build an artefact came from, not yet for matching an event to a build.

Notes:

• Only .js, .mjs and .cjs files with a sibling .map are stamped; a .map with no bundle twin is left untouched.
• Injection is idempotent — already-stamped bundles keep their id (re-runs repair a regenerated map that lost the property).
• dryRun: true skips injection entirely; dry runs never mutate artefacts.
• A per-file failure (e.g. an unparsable .map) is logged, that pair is skipped, and the build continues. bailOnError does not apply to per-file failures — it only re-throws when the whole injection run fails, e.g. the dist path cannot be walked. (Upload differs: there, bailOnError: true does abort on the first per-file failure.)
• Programmatic use: injectDebugIds(distPath) and generateDebugId() are exported from the package root.

Programmatic API

If your build script doesn't fit any of the four bundler shapes, call the runner directly:

import { runUploadFromOptions, deriveRelease } from "@browsonic/build-tools";

await runUploadFromOptions({ appKey: "web" }, "dist");

The signature is (options, distPath, cwd?). Same option type as the plugins; same env fallbacks. injectDebugIds(distPath, { logger? }) runs the Debug IDs stamping on its own.

What this package does NOT do

• Strip the sourceMappingURL comment itself — that's a bundler config (sourcemap: 'hidden' for Vite/Rollup, devtool: 'hidden-source-map' for Webpack). The plugin assumes the user has already chosen the right source-map mode.
• Symbolicate locally. Symbolication happens server-side and on demand, not automatically: the dashboard's event detail page has a Symbolicate button that POSTs the minified frames to /v1/symbolicate, which resolves them against the maps uploaded for that (appKey, release). The plugin only ships the .map files.

License

Apache-2.0.