Source Maps

Install

npm install -D @tracekit/vite-plugin

Configuration

// vite.config.ts
import { defineConfig } from 'vite';
import { tracekitVitePlugin } from '@tracekit/vite-plugin';

export default defineConfig({
  build: { sourcemap: true },  // Required: enable source maps
  plugins: [
    tracekitVitePlugin({
      // Auth token — reads TRACEKIT_AUTH_TOKEN env var by default
      authToken: process.env.TRACEKIT_AUTH_TOKEN,
      // Server URL — default: https://app.tracekit.dev
      url: 'https://app.tracekit.dev',
      // Release version — auto-detected from package.json if omitted
      release: '1.0.0',
      // Fail the build on upload error — default: false
      strict: false,
      // Disable the plugin entirely — default: false
      disabled: false,
      // Suppress console output — default: false
      silent: false,
    }),
  ],
});

Options

Install

npm install -D @tracekit/webpack-plugin

Configuration

// webpack.config.js
const { TracekitWebpackPlugin } = require('@tracekit/webpack-plugin');

module.exports = {
  devtool: 'source-map',  // Required: enable source maps
  plugins: [
    new TracekitWebpackPlugin({
      // Auth token — reads TRACEKIT_AUTH_TOKEN env var by default
      authToken: process.env.TRACEKIT_AUTH_TOKEN,
      // Server URL — default: https://app.tracekit.dev
      url: 'https://app.tracekit.dev',
      // Release version — auto-detected from package.json if omitted
      release: '1.0.0',
      // Fail the build on upload error — default: false
      strict: false,
      // Disable the plugin entirely — default: false
      disabled: false,
      // Suppress console output — default: false
      silent: false,
    }),
  ],
};

Options

Recursively discovers .js.map files in the given directory, injects debug IDs (ECMA-426 format: //# debugId=<uuid>) into both the .js and .js.map files, and uploads the source maps to the TraceKit server.

Debug ID injection is idempotent: existing debug IDs in .js files are preserved on re-run. If no path is provided, the current directory is scanned. node_modules directories are automatically skipped.

Flags

Examples

# Upload source maps from dist directory
tracekit sourcemaps upload ./dist

# Upload with explicit release version
tracekit sourcemaps upload ./dist --release v1.2.3

# Upload from current directory
tracekit sourcemaps upload

# JSON output for CI pipelines
tracekit sourcemaps upload ./dist --release v1.2.3 --json

Delete all source maps associated with a specific release. Useful for rotating old releases or re-uploading corrected maps.

Flags

Examples

# Delete source maps for a release
tracekit sourcemaps delete --release v1.2.3

# Delete with JSON output
tracekit sourcemaps delete --release v1.2.3 --json

Upload a source map file. Uses multipart/form-data encoding.

Form fields

Example (curl)

curl -X POST https://app.tracekit.dev/api/sourcemaps \
  -H "X-API-Key: your-private-api-key" \
  -F "debug_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "release=v1.2.3" \
  -F "sourcemap=@./dist/main.abc123.js.map"

Delete all source maps for a specific release.

Query parameters

Response 200 OK

{
  "deleted_count": 5,
  "release": "v1.2.3"
}

If your production error stack traces are not being resolved, check that debug IDs are present in your built .js files.

# Check for debug IDs in built files
grep -r "debugId=" ./dist/*.js

# You should see lines like:
# //# debugId=550e8400-e29b-41d4-a716-446655440000

If no debug IDs are found: (1) verify your build plugin is installed and configured, (2) check that CI=true is set in your CI environment (plugins skip local builds), (3) if using the CLI, run tracekit sourcemaps upload which injects IDs during upload.

Common causes of upload failures:

• - Authentication error: Verify your TRACEKIT_AUTH_TOKEN environment variable is set correctly, or pass authToken in the plugin config.
• - Network timeout: The CLI uses a 60-second timeout for large source maps. If your maps are very large, check your network connection.
• - No .js.map files found: Verify that source maps are being generated. For Vite, set build.sourcemap: true. For Webpack, set devtool: 'source-map'.

# Test upload manually to see detailed errors
tracekit sourcemaps upload ./dist --release v1.2.3

# Verify auth
tracekit status

If errors appear with minified stack traces despite uploading source maps:

• - Debug ID mismatch: The debug IDs in your production bundles must match the ones in the uploaded source maps. Re-building and re-uploading without using the same build output will generate different IDs.
• - Wrong release: If you tagged source maps with a specific release, verify the production build is using the same release version in its SDK config.
• - Expired maps: Source maps are retained for 90 days. If your release is older, re-upload the source maps.

If source maps were uploaded with the wrong release tag, delete them and re-upload with the correct release:

# Delete maps for the wrong release
tracekit sourcemaps delete --release wrong-version

# Re-upload with the correct release
tracekit sourcemaps upload ./dist --release v1.2.3

To verify that source maps were uploaded successfully, use the --json flag during upload to see detailed results:

tracekit sourcemaps upload ./dist --release v1.2.3 --json

# Output:
# [
#   {
#     "debug_id": "550e8400-e29b-41d4-a716-446655440000",
#     "filename": "main.abc123.js.map",
#     "size_bytes": 245760,
#     "release": "v1.2.3"
#   }
# ]