Problem
The tarball ships 1100 source-map files, all of them dangling. declarationMap and
sourceMap are on, but files publishes only dist/, so every map's sources entry
points at ../src/*.ts — a directory that is not in the package. None of them carry
sourcesContent, so there is no fallback either.
The consumer-visible effect: go-to-definition on any actor-ts symbol follows the
.d.ts.map, fails to find the .ts, and lands on the generated declaration instead;
a debugger stepping into framework code has nothing to show. Both features are worse
than if the maps were absent — a missing map degrades cleanly, a dangling one makes the
tool hunt for a file that will never appear.
The cost is 35% of the published bytes for a feature that cannot work.
Evidence
Both flags on:
tsconfig.json:11-12
"declarationMap": true,
"sourceMap": true,
src/ not published:
package.json:36-41
"files": [
"dist/",
"README.md",
"CHANGELOG.md",
"LICENSE"
],
The emitted map, as installed from the tarball:
node_modules/actor-ts/dist/index.js.map (first 120 bytes)
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,
node_modules/actor-ts/dist/index.d.ts.map (first 120 bytes)
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,IAAI,EACJ,
../src/index.ts resolves, from the installed dist/, to
node_modules/actor-ts/src/index.ts. The installed package contains exactly four
entries: CHANGELOG.md, LICENSE, README.md, dist, package.json.
Census of the installed package:
js 550 files 2.34 MB 36.5%
d.ts 550 files 1.55 MB 24.1%
js.map 550 files 1.55 MB 24.0%
d.ts.map 550 files 0.70 MB 10.8%
other 4 files 0.29 MB 4.6%
TOTAL 6.43 MB
maps: 1100 files 2.24 MB = 35% of the package
Proposal
Three coherent options; the project should pick one rather than keep the current state,
which is the only one that costs bytes and delivers nothing.
-
Drop the maps — "declarationMap": false, "sourceMap": false in the build
tsconfig. Removes 1100 files and 2.24 MB, and go-to-definition still lands on the
.d.ts, which is the same place it lands today. Smallest change, no loss.
-
Ship src/ — add "src/" to files. Costs roughly what the maps already cost,
and in exchange go-to-definition reaches the real TypeScript, which is a genuinely
better authoring experience for a framework people read the internals of. This is the
option most type-heavy libraries take.
-
Inline the sources — "inlineSources": true alongside the existing flags. Maps
become self-contained (sourcesContent populated), no src/ in the tarball, but the
maps grow by roughly the size of src/.
Option 1 or 2. Option 3 is strictly worse than 2 for the same bytes, since it gives the
debugger the source but not the editor.
Note this interacts with #820 (per-subpath bundle-size budget): whichever option
lands changes the baseline that budget would be measured against, so it is worth doing
first.
Acceptance sketch
Verification status
Reproduced by execution. bunx tsc → npm pack --pack-destination <scratch> → npm install into a throwaway directory outside the repo. Every .map under the installed
dist/ was parsed and each sources entry resolved relative to the map's own directory:
map files: 1100 | with sourcesContent: 0 | dangling source refs: 1100
1100 of 1100 dangle; none carries inline content. The byte census above is measured on
the installed tree. git status --porcelain is clean afterwards; dist/ is gitignored.
(The original review note said 37% of 6.13 MB; the difference is packed-versus-installed
measurement. The count of dangling maps — all of them — is the same either way.)
Part of the production-readiness review batch — tracked in #913.
Problem
The tarball ships 1100 source-map files, all of them dangling.
declarationMapandsourceMapare on, butfilespublishes onlydist/, so every map'ssourcesentrypoints at
../src/*.ts— a directory that is not in the package. None of them carrysourcesContent, so there is no fallback either.The consumer-visible effect: go-to-definition on any
actor-tssymbol follows the.d.ts.map, fails to find the.ts, and lands on the generated declaration instead;a debugger stepping into framework code has nothing to show. Both features are worse
than if the maps were absent — a missing map degrades cleanly, a dangling one makes the
tool hunt for a file that will never appear.
The cost is 35% of the published bytes for a feature that cannot work.
Evidence
Both flags on:
src/not published:The emitted map, as installed from the tarball:
../src/index.tsresolves, from the installeddist/, tonode_modules/actor-ts/src/index.ts. The installed package contains exactly fourentries:
CHANGELOG.md,LICENSE,README.md,dist,package.json.Census of the installed package:
Proposal
Three coherent options; the project should pick one rather than keep the current state,
which is the only one that costs bytes and delivers nothing.
Drop the maps —
"declarationMap": false, "sourceMap": falsein the buildtsconfig. Removes 1100 files and 2.24 MB, and go-to-definition still lands on the
.d.ts, which is the same place it lands today. Smallest change, no loss.Ship
src/— add"src/"tofiles. Costs roughly what the maps already cost,and in exchange go-to-definition reaches the real TypeScript, which is a genuinely
better authoring experience for a framework people read the internals of. This is the
option most type-heavy libraries take.
Inline the sources —
"inlineSources": truealongside the existing flags. Mapsbecome self-contained (
sourcesContentpopulated), nosrc/in the tarball, but themaps grow by roughly the size of
src/.Option 1 or 2. Option 3 is strictly worse than 2 for the same bytes, since it gives the
debugger the source but not the editor.
Note this interacts with #820 (per-subpath bundle-size budget): whichever option
lands changes the baseline that budget would be measured against, so it is worth doing
first.
Acceptance sketch
.mapfile in the tarball references a path that is not in the tarball.npm packoutput either contains no maps, or containssrc/, or contains maps withsourcesContent.publintandattwstay green.Verification status
Reproduced by execution.
bunx tsc→npm pack --pack-destination <scratch>→npm installinto a throwaway directory outside the repo. Every.mapunder the installeddist/was parsed and eachsourcesentry resolved relative to the map's own directory:1100 of 1100 dangle; none carries inline content. The byte census above is measured on
the installed tree.
git status --porcelainis clean afterwards;dist/is gitignored.(The original review note said 37% of 6.13 MB; the difference is packed-versus-installed
measurement. The count of dangling maps — all of them — is the same either way.)
Part of the production-readiness review batch — tracked in #913.