@tracescout/vite-plugin
v1.0.1
Published
TraceScout Vite/Rollup plugin — per-chunk debug-ID injection and private source-map upload for stack-trace symbolication.
Maintainers
Readme
@tracescout/vite-plugin
TraceScout Vite (and plain Rollup) plugin — per-chunk debug-ID injection and private source-map upload for stack-trace symbolication.
Install
npm install --save-dev @tracescout/vite-pluginNode.js ≥ 18.
Usage
import { defineConfig } from "vite";
import { tracescoutSourceMaps } from "@tracescout/vite-plugin";
export default defineConfig({
plugins: [
tracescoutSourceMaps({
project: process.env.TRACESCOUT_PROJECT_ID,
release: process.env.TRACESCOUT_RELEASE,
dist: "web",
authToken: process.env.TRACESCOUT_AUTH_TOKEN,
}),
],
build: { sourcemap: "hidden" },
});Every production build then:
- injects a deterministic per-chunk debug ID into each emitted JS chunk AND its source map (multiple chunks and dynamic imports each get their own ID — never one ID per build),
- publishes the entry chunk's ID for the TraceScout Browser SDK
(
window.__TRACESCOUT_DEBUG_ID__, injected into the HTML<head>so it is set beforeTraceScout.init()runs), - uploads every map privately to TraceScout after a successful build, through
the same shared upload core as
@tracescout/cli(retries, backoff, idempotency, secret redaction).
build.sourcemap: "hidden" is recommended: maps are generated for upload but
never referenced from — or served with — your deployed bundles.
Options
| Option | Meaning | Default |
|---|---|---|
| project | TraceScout project id | TRACESCOUT_PROJECT_ID |
| release | Release identifying this build | TRACESCOUT_RELEASE |
| dist | Build variant | TRACESCOUT_DIST |
| authToken | Scoped upload token | TRACESCOUT_AUTH_TOKEN |
| apiUrl | API base | https://api.tracescout.com |
| urlPrefix | Artifact URL identity prefix | ~/ |
| sourcesContentPolicy | strip | retain | reject | server default (strip) |
| upload | false = inject only | true |
| deleteMapsAfterUpload | Delete local .map files after a FULLY successful upload (never after a failure) | false |
| errorHandling | "warn" keeps the build green; "error" fails the build on upload failure | "warn" |
| uploadInWatch | Upload during watch builds | false (dev/watch never uploads) |
| dryRun, quiet, debug, concurrency, timeoutMs, retries | As in the CLI | — |
Notes
- Chunk filenames (hashes) are computed before injection and are preserved; the file content changes only by appended comments — line numbers are unchanged, so source maps stay aligned.
- Works as a plain Rollup plugin too (standard
generateBundle/closeBundlehooks); the HTML head injection applies only when an HTML asset is emitted. - The auth token is never logged; upload errors are redacted.
Docs: https://docs.tracescout.com/docs/guides/source-maps
License
Apache-2.0. TraceScout names and logos are trademarks of TraceScout — no trademark rights are granted.
