@tracescout/webpack-plugin

TraceScout webpack 5 plugin — per-artifact debug-ID injection and private source-map upload for stack-trace symbolication.

Uses the same shared core as @tracescout/cli and @tracescout/vite-plugin: one debug-ID library, one upload transport, one retry/idempotency policy, one redacting logger. There is no webpack-specific upload implementation.

Install

npm install --save-dev @tracescout/webpack-plugin

Node.js ≥ 18, webpack ≥ 5 (peer dependency).

Usage

const { TracescoutSourceMapsPlugin } = require('@tracescout/webpack-plugin');

module.exports = {
  mode: 'production',
  devtool: 'hidden-source-map',
  plugins: [
    new TracescoutSourceMapsPlugin({
      project: process.env.TRACESCOUT_PROJECT_ID,
      release: process.env.TRACESCOUT_RELEASE,
      dist: 'web',
      authToken: process.env.TRACESCOUT_AUTH_TOKEN,
    }),
  ],
};

Every production build then:

1. gives each emitted JS artifact that has a .map its own deterministic debug ID, injected into both the code (//# debugId=) and the map ("debugId") — code-split and dynamically imported chunks each get their own, never one ID per build;
2. publishes the entry/runtime chunk's ID for the TraceScout Browser SDK as window.__TRACESCOUT_DEBUG_ID__ (also injected into any emitted HTML as a head-level classic <script>, so it is set before a deferred bundle runs);
3. uploads every written map privately to TraceScout — only after a successful compilation.

devtool: 'hidden-source-map' is recommended: maps are generated for upload but never referenced from your deployed bundles. Don't deploy the .map files (or set deleteMapsAfterUpload: true).

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 (never logged) | 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 maps after a FULLY successful upload (never after a failure) | false | | errorHandling | "error" fails the build on upload failure; "warn" keeps it green | "warn" | | uploadInWatch | Upload during watch builds | false | | dryRun, quiet, debug, concurrency, timeoutMs, retries | As in the CLI | — |

Notes and trade-offs

• Filename hashes are preserved. webpack computes [contenthash] before this plugin runs (it injects at PROCESS_ASSETS_STAGE_REPORT, after the devtool plugins emit the maps), so file names never change. File content changes by an appended comment.
• The entry snippet is appended, never prepended. Prepending would shift every generated line down while the map still maps the original lines, silently breaking symbolication for that whole chunk.
• A failed compilation never uploads, and a failed upload never deletes maps.
• Windows/POSIX: artifact URL identities always use /, whatever the host path style.
• Server bundles: this plugin uploads whatever webpack wrote to output.path. Point it at your browser build; Browser SDK symbolication only matches browser artifacts.

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.