Source Maps

When your app is deployed, the code running in production is minified — variable names are shortened, whitespace is removed, and everything is bundled into a few large files. This makes stack traces nearly impossible to read.

Source maps fix that. They let DeepTracer translate minified stack traces back to your original source code — the real file names, function names, and line numbers you wrote.

How it works

1. During build — Your source map files (.map) are uploaded to DeepTracer, tagged with a release ID
2. At runtime — When an error happens, the SDK sends it with the same release ID
3. On the dashboard — DeepTracer matches the error's stack trace against your uploaded source maps and shows you the original code

Without source maps, a stack trace looks like this:

Error: Cannot read property 'id' of undefined
  at a.js:1:28394
  at n.js:1:9823

With source maps, it becomes:

Error: Cannot read property 'id' of undefined
  at getUser (src/lib/users.ts:42:12)
  at handleRequest (src/app/api/users/route.ts:18:8)

Much better.

Setup for Next.js

Wrap your Next.js config with withDeepTracer — source maps are uploaded automatically during next build:

import { withDeepTracer } from "@deeptracer/nextjs/config"

export default withDeepTracer({
  // your existing Next.js config
})

Source map upload is auto-enabled when any of these are true:

• You're deploying on Vercel (VERCEL=1)
• You're running in CI (CI=true)
• You explicitly opt in (DEEPTRACER_UPLOAD_SOURCEMAPS=true)

Required environment variables

Explicit configuration

You can also pass options directly instead of using environment variables:

export default withDeepTracer(
  { reactStrictMode: true },
  {
    uploadSourceMaps: true,
    release: "v1.2.3",
    endpoint: "https://ingest.deeptracer.dev",
    apiKey: "dt_your_api_key",
    deleteSourceMapsAfterUpload: true,
  },
)

How matching works

When an error arrives with a release field, DeepTracer:

1. Parses the stack trace into individual frames (file, line, column)
2. Looks up the matching .map file using the release ID and filename
3. Tries progressively shorter paths to handle different serving URLs — so _next/static/chunks/app.js also matches chunks/app.js and app.js
4. Resolves each frame to the original source location

The key rule: the release ID on the error must match the release ID used when uploading. If they don't match, DeepTracer shows the raw minified stack trace instead.

Security

Source maps contain your original source code, so DeepTracer keeps them private:

• Blocked from browsers — The Next.js plugin adds a rewrite rule that returns 404 for any *.map request
• Private storage — Uploaded maps are stored in authenticated storage, only accessible by DeepTracer's backend
• Project isolation — Source maps are scoped to your project and can't be accessed by others
• Optional deletion — Set deleteSourceMapsAfterUpload: true to remove .map files from your build output after upload

Troubleshooting

Source maps not resolving? Check these three things:

1. Release matches — The release sent with errors must exactly match the release used when uploading source maps
2. Upload succeeded — Look for [@deeptracer/nextjs] Uploaded N source map(s) in your build logs
3. Error has a release — Errors without a release field can't be resolved

What's next?