@browsonic/build-tools weekly downloads statistics

@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.4.0, and it matches main. Published 2026-09-05 (1.3.0 refuses to stamp a bundle that index.html pins with an SRI hash; 1.2.3 before it, 2026-09-02) together with its pinned dependency @browsonic/cli 1.2.5. 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

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

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

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

Rollup

esbuild

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.

Angular CLI

The Angular CLI exposes no plugin hook, so none of the bundler plugins above apply. Emit hidden maps and upload them after the build:

Angular 17+ writes to dist//browser. --release must equal the SDK's clientVersion (or release) and change per build. Debug ids can be stamped afterwards with injectDebugIds('dist/'), but not with subresourceIntegrity: true — the CLI's integrity= hashes in index.html cover the pre-stamp bytes, and injectDebugIds refuses when it finds them. The full recipe is in the SDK's INTEGRATION.md (Angular section).

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.)_…

Description from the npm listing.