04/sourcemaps

Source Map Vault & Production Debugging

Never ship .js.map files to public users again, while retaining full stack-trace symbolication in Sentry, Datadog, or local crash triage.

How .unpeek-maps/ Isolation Works

Leaving `.map` files in your public build folder allows anyone to reconstruct your exact TypeScript source tree in Chrome DevTools with a single click. Conversely, disabling source maps entirely blinds your engineering team during production incidents.

unpeek resolves this dilemma automatically during `unpeek protect`:

  • Scans the target build directory recursively for all `*.map` files, flattening ECMA-426 `.sections` index maps automatically.
  • Composes multi-pass $M_1 \circ M_2$ VLQ mappings (`chainSourceMaps`) with preamble line shifting and decodes URL-encoded Next.js segments (`%28public%29`, `%5Bparam%5D`) plus Windows paths.
  • Stamps an identical deterministic SHA-256 `debugId` onto both the protected JS bundle and vaulted `.map` (verified by `unpeek check` via `debugid-mismatch`), relocates maps to `.unpeek-maps/`, and strips `//# sourceMappingURL=...` directives.

Uploading Vaulted Maps to Sentry / Datadog in CI

After `unpeek protect` completes in your CI workflow, point your observability CLI (`sentry-cli` or `datadog-ci`) at `.unpeek-maps/` to upload private debugging symbols, then discard the folder before deploying your static artifact.

GitHub Actions: Upload .unpeek-maps to Sentry
- name: Build & Protect Client Bundles
  run: |
    pnpm build
    npx unpeek protect

- name: Upload Private Source Maps to Sentry
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx @sentry/cli sourcemaps upload \
      --org acme-corp \
      --project web-client \
      .unpeek-maps

Docker Image Hardening & .dockerignore Advisory

When packaging applications with Docker using `COPY . .`, private debugging symbols inside `.unpeek-maps/` can leak into public container image layers if `.dockerignore` is missing or omits `.unpeek-maps/`.

`unpeek protect` automatically inspects `.dockerignore`. If present, it appends `.unpeek-maps/`; if `.dockerignore` is missing or lacks the rule, it emits an advisory warning:

  • `[unpeek:advisory] .dockerignore is missing .unpeek-maps/. Private maps may leak into Docker image during 'COPY . .'.`
  • Always ensure `.unpeek-maps/` is listed in `.dockerignore` alongside `.gitignore` before shipping Docker images.