Skip to content

fix(build): stop publishing dangling source/declaration maps#36

Open
dmchaledev wants to merge 1 commit into
mainfrom
claude/magical-ptolemy-pk8blg
Open

fix(build): stop publishing dangling source/declaration maps#36
dmchaledev wants to merge 1 commit into
mainfrom
claude/magical-ptolemy-pk8blg

Conversation

@dmchaledev

Copy link
Copy Markdown
Contributor

Summary

The published npm tarball ships 12 map files that all point at source that isn't in the package. package.json's files field publishes dist only (not src), but the build emits *.js.map and *.d.ts.map whose sources all reference ../src/*.ts. Since src/ is never published, every one of those maps is a dangling pointer.

Concretely, on the current main:

$ npm run build && node -p "JSON.parse(require('fs').readFileSync('dist/diff.d.ts.map','utf8')).sources"
[ '../src/diff.ts' ]          # <- not in the tarball

$ npm pack --dry-run          # 28 files, unpacked 49.5 kB
  dist/diff.js.map            # references ../src/diff.ts (absent)
  dist/diff.d.ts.map          # references ../src/diff.ts (absent)
  ... 12 map files total, 0 src files

Impact

  • Declaration maps (.d.ts.map) exist for exactly one reason: IDE "Go to Definition" jumping from a consumer's editor into the original .ts. With src/ absent, that navigation resolves to a file that doesn't exist — the feature is shipped broken and misleading.
  • Source maps (.js.map) break debugger source mapping the same way: stepping into the library resolves to non-existent ../src/*.ts.
  • Dead weight: ~21 kB of the 49.5 kB unpacked size is maps that can never resolve.

Change

Disable sourceMap and declarationMap in tsconfig.build.json (the config used by npm run build → the published dist). declaration: true is kept — the .d.ts types are public API and must stay. Local dev/typecheck config (tsconfig.json) is untouched.

This makes the package internally consistent: it stops shipping maps it can't back with source.

Result

              main        this PR
files          28           16
map files      12            0
.d.ts files     6            6   (unchanged)
unpacked     49.5 kB      28.6 kB

Alternative considered

The other way to make the maps resolve is to add src to files and keep the maps, giving consumers go-to-definition into real TS. That's a legitimate product choice but bloats the tarball with raw sources; for a compiled library, dropping the maps is the standard, minimal-footprint fix. Happy to switch to the ship-src approach instead if source navigation into the package is desired.

Verification

  • npm run typecheck — clean
  • npm run lint — clean
  • npm test — 29/29 pass
  • npm run build + CLI smoke test — unchanged output; dist now contains .js + .d.ts only
  • npm pack --dry-run — 0 map files, 6 .d.ts retained

Not a duplicate

None of the open issues (#9, #21, #22, #26, #27, #30) or PRs touch source maps, the files array, or published tarball integrity. This is confined to one build-config file and composes cleanly with everything in flight.

🤖 Generated with Claude Code

https://claude.ai/code/session_0121jPWdufr9tbgebBZAa5f9


Generated by Claude Code

The published tarball ships `dist` only (package.json "files"), not `src`,
but the build emitted .js.map and .d.ts.map files that all reference
../src/*.ts. Those source files are absent from the package, so every map
was a dangling pointer: debugger source mapping and IDE "Go to Definition"
(the whole purpose of declaration maps) resolved to files that don't exist.

Disable sourceMap and declarationMap in tsconfig.build.json (keeping
declaration:true — the .d.ts types are public API). This removes 12 broken
map files from the tarball and cuts unpacked size 49.5kB -> 28.6kB.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0121jPWdufr9tbgebBZAa5f9
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants