@tracescout/esbuild-plugin

TraceScout esbuild plugin — per-output debug-ID injection and private source-map upload for stack-trace symbolication. Supports ESM/CJS/IIFE, TypeScript, multiple entry points, code splitting, minification, and external ("hidden") source maps.

Reuses the same shared core as @tracescout/cli, @tracescout/vite-plugin, @tracescout/webpack-plugin, @tracescout/nextjs, and @tracescout/nuxt — no esbuild-specific upload implementation.

Install

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

Usage

const esbuild = require('esbuild');
const { tracescoutSourceMaps } = require('@tracescout/esbuild-plugin');

await esbuild.build({
  entryPoints: ['src/main.ts', 'src/admin.ts'],
  bundle: true,
  splitting: true,
  format: 'esm',
  minify: true,
  outdir: 'dist',
  sourcemap: 'external',        // hidden pattern: no sourceMappingURL comment
  plugins: [tracescoutSourceMaps({
    project: process.env.TRACESCOUT_PROJECT_ID,
    release: process.env.TRACESCOUT_RELEASE,
    dist: 'web',
    authToken: process.env.TRACESCOUT_AUTH_TOKEN,
    urlPrefix: '~/assets',      // host-agnostic path where dist/ is served
    deleteMapsAfterUpload: true,
  })],
});

Every emitted JS output gets a deterministic debug ID (derived from its own bytes) injected into both code and map; the configured entry outputs additionally publish window.__TRACESCOUT_DEBUG_ID__ for the browser SDK. Dynamic-import chunks get their own IDs but never publish the global (the metafile marks them entryPoint too — the plugin filters against the configured entry points so a late-loading chunk can't clobber the entry ID).

Maps upload privately after a successful build; deleteMapsAfterUpload removes local maps only after a fully successful upload. With sourcemap: 'linked'/true, add stripSourceMappingURL: true to hide the comment post-upload. write: false builds are not supported for upload.

Set the same release on TraceScout.init():

TraceScout.init('YOUR_PROJECT_ID', { release: process.env.TS_RELEASE, dist: 'web' });

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.