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.
- 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-mapsDocker 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.