Source Maps

Upload source maps to Traceway so that minified stack traces in production exceptions are automatically deobfuscated.

Installation

npm install -D @tracewayapp/sourcemap-upload

This provides the traceway-sourcemaps CLI command.

Getting an Upload Token

Uploads authenticate with a dedicated upload token, not the project token your SDK uses. Generate it in the dashboard: open the Connection page for your project, scroll to the Source Maps section, and click Generate Upload Token. The token is per-project and can be copied from the same place later.

Treat it like any other CI secret. Regenerate issues a new token and invalidates the current one immediately, so any pipeline still using the old token fails to upload until its secret is updated. Members with the readonly role cannot generate or regenerate tokens; ask an organization admin.

Usage

traceway-sourcemaps \
  --url https://your-traceway-instance.com \
  --token your-sourcemap-token \
  --directory ./dist

The CLI recursively finds all *.map files in the specified directory and uploads them to Traceway via POST /api/sourcemaps/upload, together with the sibling .js/.cjs/.mjs bundle next to each map when one exists. The bundle is what lets the backend resolve the enclosing function name for each frame; without it, symbolication still resolves file, line, and column but leaves function names as the browser reported them.

On self-hosted instances, uploaded files land in the backend's blob storage; configure S3 or a persistent volume there before wiring uploads into CI, or the maps disappear when the container is recreated.

CLI Options

Flag	Required	Description
`--url <url>`	Yes	Traceway backend URL
`--token <token>`	Yes	Source map upload token
`--directory <dir>`	No	Directory to search (default: current directory)

Environment Variables

Instead of passing flags, you can set environment variables:

Variable	Equivalent Flag
`TRACEWAY_URL`	`--url`
`TRACEWAY_SOURCEMAP_TOKEN`	`--token`

Flags take precedence over environment variables when both are set.

Limits

Individual source map files must not exceed 50MB.

Maps Without Source File Names

Some build pipelines produce source maps where the sources array contains null entries: the mappings and embedded source content are intact, but the original file names are missing. Traceway still deobfuscates these frames, resolving the line, column, and function name, and shows <unknown> in place of the file name (e.g. <unknown>:3:9). To get real file names in stack traces, configure your bundler to emit sources entries in its source maps.

CI/CD Example (GitHub Actions)

name: Deploy
on:
  push:
    branches: [main]
 
jobs:
  deploy: