Roadmap: reliability and performance as first-class citizens

[mhenrixon]

Roadmap: reliability and performance as first-class citizens

Problem / Goal

importmap-plus already does what importmap-rails does plus minification, esm.run bundles, version locks and provenance. Two things still make an app depend on a CDN at runtime or on a developer's vigilance:

1. Packages that can't be vendored as one file. A live probe of 20 popular packages through jspm today: 9 of 18 that resolved ship a file that imports siblings by relative path (import"./_/f08a6ffe.js", from"../_/f09ec963.js", import('../photoswipe.js')), pdfjs-dist also spawns new Worker(…), ace-builds too, and 2 (@mui/material, mermaid) don't resolve on jspm at all. pin vendors the entry anyway and the browser 404s on the siblings. Upstream calls this expected behaviour (Relative paths in importmaps js default to my domain rails/importmap-rails#295, Supporting package directory downloads rails/importmap-rails#302 open since 2024, Download all the files associated with a package from a CDN rails/importmap-rails#235 stalled on Propshaft not rewriting imports). An app on this gem is holding @basis-theory/web-elements at 2.x for exactly this reason.
2. No verification, no fallback, no tuning. jspm 404s or lags npm and pin just gives up; a remote pin ships without an integrity hash; nothing checks the app's import map before a page does; every preload: true pin is preloaded on every page (a real app had to hand-write preload: false on apexcharts/core to stop 1.1 MB per page); modulepreload links wait for the HTML.

Done looks like: bin/importmap pin always ends with a working pin — vendored with its whole file graph when it can be, remote with a recorded reason and an integrity hash when it can't, from whichever CDN can actually serve the registry's latest — bin/importmap doctor proves the app's map in CI, and the page preloads what it will use, as early as the server allows.

The pieces, in execution order

#	Issue	Layer	Depends on
1	#14 pin keeps a package remote when its file can't stand alone, and says why	CLI + Packager	— (bumps VERSION to 1.2.0)
2	#15 registry-latest resolution and jspm → esm.run → jsdelivr fallback	CLI + Packager + Npm	#14
3	#16 remote pins get a subresource-integrity hash	CLI + Packager	#14
4	#17 pin vendors a package's whole file graph	Packager (new collaborator)	#14
5	#18 bin/importmap doctor	CLI (new collaborators)	#14, #16
6	#19 graph-aware preloading (config.importmap.preload_strategy = :reachable)	Map + engine (request path)	#18
7	#20 103 Early Hints for modulepreload	helper + engine	best after #19

Each child issue is self-contained: context files, the decision with rejected alternatives, ordered TDD steps, verification gates, out-of-scope. Run them one at a time with /lfg <number>; each is one PR.

Rules that apply to every child

• Importmap::VERSION moves once: pin keeps a package remote when its file cannot stand alone, and says why #14 sets it to 1.2.0 and commits Gemfile.lock + docs/Gemfile.lock; no later child bumps it. UPSTREAM_VERSION is untouched.
• CHANGELOG.md: every child adds under ## 1.2.0 → ### Added (create the heading in pin keeps a package remote when its file cannot stand alone, and says why #14).
• Upstream-owned files get additive edits only (packager.rb is at its 551-line limit — new behaviour goes in fork-only collaborators: module_inspector.rb, provider_chain.rb, integrity.rb, package_graph.rb, import_scanner.rb, doctor.rb, graph.rb, early_hints.rb). Upstream style in upstream files.
• Every outbound request through with_retries; no network on the request path (Graph-aware preloading: preload what the entry point actually reaches #19 reads local files only, cached like the JSON; javascript_importmap_tags sends modulepreload links as 103 Early Hints #20 sends a header).
• Pins this gem writes stay readable by importmap-rails: the new provenance details (remote: <reason>, (graph of <pkg>)) are comments; pin_all_from for graph files is upstream's own DSL.
• Live tests (test/commands_test.rb) only for a new CDN contract or a new printed sentence; exact versions; one runner at a time.
• Docs: the pages each child names, plus after pin vendors a package whole file graph, so chunked packages no longer need a CDN #17 a new page "Multi-file packages" under the Vendoring group (cd docs && bin/rails g docs_kit:page "Multi-file packages" --group=Vendoring) that tells the whole story: detection → reasons → graph vendoring → --vendor / --remote → doctor.

Settled in interview (do not re-litigate)

• Epic + child issues, executed in order.
• Reason recorded in the provenance comment: # @<ver> (remote: <reason>), detail order provider, minified, remote, locked.
• Phase 2 vendors the file graph (flat entry + vendor/javascript/<pkg>/ directory + one pin_all_from line with relative imports rewritten to bare keys), not a public/ mirror.
• Fallback is automatic: registry latest first, then jspm → esm.run → jsdelivr; --from disables it.
• Roadmap scope: doctor, remote SRI, graph-aware preloading, Early Hints — all in.

Upstream-first notes

#19 (graph-aware preloading) and #20 (Early Hints) are not fork-specific; propose them to rails/importmap-rails after they land here so the next sync shrinks the diff. #14, #15, #16, #17, #18 lean on fork provenance or on behaviour upstream has declined.

Evidence

• Live probe (2026-09-12) of jspm's generate API and downloads for 20 packages; crawl of lodash-es (464 files), date-fns (258), @popperjs/core (48) — closed sets matching jspm's staticDeps.
• Propshaft::Compiler::JsAssetUrls rewrites only RAILS_ASSET_URL(); Sprockets rewrites nothing — relative imports in digested files can't work without the CLI rewriting them.
• jspm's generate API returns map.integrity when asked; Remote pins get a subresource-integrity hash when they are written #16 hashes locally instead so every provider is covered.
• rails/importmap-rails: Supporting package directory downloads rails/importmap-rails#302 (open), Download all the files associated with a package from a CDN rails/importmap-rails#235 (stalled PR), Relative paths in importmaps js default to my domain rails/importmap-rails#295, How to import a web worker javascript file? rails/importmap-rails#278, importmap pin --download does not work for multi-files dependencies rails/importmap-rails#153, Popper.js not working when --download is used rails/importmap-rails#65.

Execution

Start with /lfg 14.

[mhenrixon]

Every piece of this roadmap has landed on main.

#	Issue	State
1	#14 pin keeps a package remote when its file can't stand alone	closed
2	#15 registry-latest resolution and jspm → esm.run → jsdelivr fallback	closed
3	#16 remote pins get a subresource-integrity hash	closed
4	#17 pin vendors a package's whole file graph	closed
5	#18 bin/importmap doctor	closed
6	#19 graph-aware preloading (preload_strategy = :reachable)	closed
7	#20 103 Early Hints for modulepreload	closed

The cross-cutting rules held:

• All eight fork-only collaborators exist — module_inspector.rb, provider_chain.rb, integrity.rb, package_graph.rb, import_scanner.rb, doctor.rb, graph.rb, early_hints.rb.
• Importmap::VERSION moved once; UPSTREAM_VERSION was not touched by any child.
• Gemfile.lock and docs/Gemfile.lock both carry the pin.
• Every child has a CHANGELOG.md entry under the same heading.
• The "Multi-file packages" docs page was added under the Vendoring group.

#43 (closing #32 and #34) afterwards fixed a gap in #15's fallback: a batch one CDN refused took the healthy packages with it, and re-pinned them from the next CDN. A refused batch is now split before it falls back.

Closing as complete. The one item from this epic that is not done is the "Upstream-first notes" — proposing #19 and #20 to rails/importmap-rails — which is tracked separately so it isn't lost.