Skip to content

Documentation

Source maps and CLI

Upload your source maps from CI so errors show your original file and line, not minified JavaScript.

In production your JavaScript is minified: an error says index-3fa2.js:1:48211. If you upload the source maps for each release, Wutbug translates stack traces back to your original code (file, line and code snippet) in the dashboard and in responses from the MCP server.

How it works

  1. Your build generates .map files next to the .js files.
  2. In CI, the CLI uploads the .map files with a release identifier (--release).
  3. Your app initializes the SDK with the same release.
  4. When a report arrives, Wutbug looks up the maps for that release by the URL of each file in the stack trace.

1. Pass the release to the SDK

TypeScript
wutbug.init({
  projectKey: 'pk_your_key',
  endpoint: 'https://api.wutbug.dev',
  release: import.meta.env.VITE_RELEASE, // for example the commit SHA
});

With the script tag: data-release="…".

2. Generate the source maps

ToolConfiguration
Vitebuild: { sourcemap: 'hidden' } in vite.config.ts
Next.jsproductionBrowserSourceMaps: true in next.config.ts
webpackdevtool: 'hidden-source-map'
esbuild--sourcemap=external

The hidden variants generate the .map files without the //# sourceMappingURL comment, so your source code isn't publicly exposed.

3. Upload the maps from CI

Create the project's secret key (sk_…) in the dashboard, under Projects → Source maps, and store it as a CI secret named WUTBUG_SECRET_KEY.

Terminal
npx @wutbug/cli sourcemaps upload ./dist/assets \
  --release "$GITHUB_SHA" \
  --url-prefix /assets/ \
  --api https://api.wutbug.dev \
  --delete
OptionDescription
<dir>Folder to search for *.js.map files (recursive).
--release <version>Required. The same value you pass to init({ release }).
--url-prefix <path>URL path where <dir> is served. Defaults to /. Example: if dist/assets/index-3fa2.js is served at https://app.acme.com/assets/index-3fa2.js, use /assets/.
--api <url>API URL. Defaults to $WUTBUG_API_URL.
--deleteDeletes the local .map files after uploading them, so they don't get published.
Environment variableDescription
WUTBUG_SECRET_KEYRequired. The project's secret key (sk_…).
WUTBUG_API_URLAPI URL, if you don't use --api.

Example with GitHub Actions and Vite

.github/workflows/deploy.yml
- name: Build
  run: npm run build
  env:
    VITE_RELEASE: ${{ github.sha }}

- name: Upload source maps to Wutbug
  run: npx @wutbug/cli sourcemaps upload ./dist/assets --release ${{ github.sha }} --url-prefix /assets/ --delete
  env:
    WUTBUG_SECRET_KEY: ${{ secrets.WUTBUG_SECRET_KEY }}
    WUTBUG_API_URL: https://api.wutbug.dev

Next.js

Next.js client files are served under /_next/static/:

Terminal
npx @wutbug/cli sourcemaps upload .next/static --release "$GIT_SHA" --url-prefix /_next/static/ --delete

Common problems

  • The stack trace is still minified. Check that the report's release (visible in the dashboard) is identical to the one you used when uploading, and that --url-prefix matches the actual path of the files.
  • "Set WUTBUG_SECRET_KEY…": the variable is missing or doesn't start with sk_.
  • The secret key leaked. Generate a new one in the dashboard: the old one stops working. We only store a hash of the key, so we can't show it to you again.
← PreviousAuto-captureNext →MCP / Connect AI