jspm-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d28f515c7c82e31da220cc7dca25540b499ad2f3ca9f98f0b9e9092dc31940a6
+  data.tar.gz: 2fa31fa61006a069f3d8876ce5c68e60e0e766852749ff062656a1436e67f7e6
+SHA512:
+  metadata.gz: 1dc7843f5631aa615fb7797120c6d047c74808ff08d6ec429db85b3ef1efff1a61419a35f5dd10c644df650cfd9484ea20a455ecd8ef25151714eb959678e2fa
+  data.tar.gz: 2074d972cf1e2a2fb11a8753df72228a5cb1984b43455c906e23c176d3bb8d5a110e846c43ebffe4c267544e5faedc16fab871050e9bc9fe70197bb1eee16a3b

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- `bin/rails jspm:install` traces `app/javascript/application.js` with jspm and vendors every module it reaches. It copies npm dependencies' stylesheets, fonts and images. `config/importmap.json` locks versions, and `package-lock.json` overrides it for packages installed with npm.
+- `javascript_jspm_tags` renders the import map with Propshaft's digested paths, preloads, and the entry module.
+- Modules on Propshaft's load path, including engines', are importable by asset name, the way importmap-rails pins work.
+- `bin/rails jspm:check` fails when `config/importmap.json` or `vendor/jspm` is out of date.
+- Warns when the import map can't match `package-lock.json`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clay Shentrup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,260 @@
+```
+   _                                   _  _
+  (_) ___ _ __  _ __        _ _  __ _ (_)| | ___
+  | |(_-<| '_ \| '  \  ___ | '_|/ _` || || |(_-<
+ _/ |/__/| .__/|_|_|_||___||_|  \__,_||_||_|/__/
+|__/     |_|
+```
+
+[![CI](https://github.com/ClayShentrup/jspm-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/ClayShentrup/jspm-rails/actions/workflows/ci.yml)
+
+**Import maps for Rails, built by [jspm](https://jspm.org).**
+
+Your JavaScript ships as the ES modules its authors wrote. There's no bundler, no build step and no Node in production, and the browser caches each module on its own. Use jspm alone, or install packages with npm too. npm then sets their versions, so Dependabot keeps working.
+
+```sh
+bin/rails jspm:install
+```
+
+```
+      traced  ./app/javascript/application.js
+    vendored  31 modules from ga.jspm.io
+      copied  73 assets from node_modules
+       wrote  config/importmap.json
+```
+
+## Contents
+
+- [Why](#why)
+- [Quick start](#quick-start)
+- [Writing your JavaScript](#writing-your-javascript)
+- [Versions: plain jspm, or npm too](#versions-plain-jspm-or-npm-too)
+- [Stylesheets, fonts and images](#stylesheets-fonts-and-images)
+- [Keeping up to date](#keeping-up-to-date)
+- [Warnings](#warnings)
+- [Deploying](#deploying)
+- [How it works](#how-it-works)
+- [Compared to](#compared-to)
+- [FAQ](#faq)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+## Why
+
+Rails 8 ships import maps by default, through [importmap-rails](https://github.com/rails/importmap-rails). It vendors one file per package. That works until a package imports its own internal files or depends on other packages. Then you pin the whole tree by hand, and `bin/importmap update` can't tell which versions belong together. A package spread across many modules ends up split across versions, or missing files.
+
+jspm solves that. It traces your code and finds every module your code reaches, across whole dependency trees. jspm-rails runs that trace, vendors what it finds, and hands the result to Propshaft. So you get import maps that work for any package on npm, with versions locked the way you'd expect.
+
+## Quick start
+
+You need Rails 8 with Propshaft, and Node with npm on your development machine.
+
+```sh
+bundle add jspm-rails
+npm install --save-dev @jspm/generator
+```
+
+Render the tags in your layout's `<head>`:
+
+```erb
+<%= javascript_jspm_tags %>
+```
+
+Write `app/javascript/application.js`:
+
+```js
+import confetti from 'canvas-confetti'
+
+confetti()
+```
+
+Install, and commit what it writes:
+
+```sh
+bin/rails jspm:install
+git add config/importmap.json vendor/jspm
+```
+
+Reload the page.
+
+## Writing your JavaScript
+
+**The entry point is `app/javascript/application.js`.** `javascript_jspm_tags` loads it as a module, and the install traces everything it imports.
+
+**Import packages by name,** as their documentation shows:
+
+```js
+import TomSelect from 'tom-select'
+import { Controller } from '@hotwired/stimulus'
+```
+
+**Import your own modules by asset name,** as importmap-rails pins them: the logical path without its extension, and a directory's name for its `index.js`. Relative paths work too:
+
+```js
+import { setUpForms } from 'forms'      // app/javascript/forms.js
+import 'controllers'                    // app/javascript/controllers/index.js
+import { helper } from './helpers.js'
+```
+
+**Import modules that gems ship the same way.** Every engine's `app/assets` directories are on Propshaft's load path, so a gem's modules are importable by asset name with no setup:
+
+```js
+import MathController from 'astrology/math_controller'
+```
+
+**Import rarely used code dynamically.** The install vendors it too, but the page doesn't preload it, so the browser fetches it only when it runs:
+
+```js
+const { default: katex } = await import('katex')
+```
+
+## Versions: plain jspm, or npm too
+
+**Plain jspm works on its own.** The install resolves each package you import from jspm.io. That's the latest version, or the newest within a range you give in `package.json`'s `dependencies`, as jspm does. `config/importmap.json` is jspm's lockfile: every install keeps the versions it already holds.
+
+**Install a package with npm when you want more.** Its version in `package-lock.json` then overrides the import map, and you get:
+
+- Dependabot pull requests for it.
+- Its stylesheets, fonts and images in `node_modules`, at the same version as its JavaScript.
+
+Mix the two freely. A package's JavaScript always comes from jspm.io either way. npm decides the version, not the files.
+
+## Stylesheets, fonts and images
+
+jspm.io serves JavaScript. For a package's other files, install it with npm as a dependency. The install copies the stylesheets, fonts and images of every package in `dependencies`, and their dependencies, into `vendor/jspm/<package>/`:
+
+```erb
+<%= stylesheet_link_tag 'katex/dist/katex' %>
+```
+
+Propshaft rewrites the `url()`s in the stylesheet to digested paths, so the fonts load too. The CSS comes from npm and the JavaScript from jspm.io, both at the version in `package-lock.json`.
+
+Each name starts with its package, so two packages' `style.css` never collide. `devDependencies` are build tools, so the install leaves them out.
+
+Why copy, instead of putting `node_modules` on the load path? Propshaft checks every file on its load path for changes before each request in development. With one real app's `node_modules` (8,900 files), that took a page request from 1.4 ms to 98 ms. Production would also precompile all of `node_modules` into `public/assets`.
+
+## Keeping up to date
+
+**npm packages:** when Dependabot, or you, changes `package-lock.json`, run `bin/rails jspm:install` again.
+
+**Plain jspm packages:** delete the package's entries from `config/importmap.json`, then run the install. jspm resolves it afresh.
+
+**To keep the map from drifting,** run the check in CI:
+
+```sh
+bin/rails jspm:check
+```
+
+It traces again without writing anything. It fails when an install would change `config/importmap.json`, for example after Dependabot bumps `package-lock.json`. It also fails when a module is missing from `vendor/jspm`, or a copied stylesheet, font or image no longer matches `node_modules`:
+
+```
+       stale  config/importmap.json
+         run  bin/rails jspm:install
+```
+
+## Warnings
+
+The install warns when the import map can't match `package-lock.json`:
+
+```
+        warn  @orchidjs/unicode-variants: package-lock.json has 1.1.1 and 1.2.2, and the import map uses 1.1.1 everywhere
+```
+
+npm installs two versions of a package when its dependents' ranges don't overlap. An import map gives each package one version per scope, so jspm-rails uses the top-level version everywhere and tells you. Check that the packages needing the other version still work, or upgrade them so the ranges meet.
+
+## Deploying
+
+- **Commit `config/importmap.json` and `vendor/jspm`.** `assets:precompile` digests the vendored modules like any other asset.
+- **Production needs no Node, no npm and no jspm.io.**
+- **An `asset_host` on another origin must send `Access-Control-Allow-Origin`.** Browsers load modules and fonts across origins only with CORS.
+- **Content Security Policy works.** Every tag carries the request's nonce.
+- **Turbo reloads the page when the import map changes,** because the map's tag has `data-turbo-track="reload"`.
+
+## How it works
+
+`bin/rails jspm:install`:
+
+1. Boots the app, then traces `app/javascript/application.js` with [`@jspm/generator`](https://github.com/jspm/generator). Every module on Propshaft's load path is importable by asset name. The previous `config/importmap.json` locks versions, and `package-lock.json` pins every package npm installed. Only packages your code reaches end up in the map, so KaTeX's command-line dependency stays out.
+2. Downloads each traced module from jspm.io, with its source map, into `vendor/jspm/ga.jspm.io`.
+3. Copies each npm dependency's stylesheets, fonts and images into `vendor/jspm/<package>/`.
+4. Writes jspm's import map to `config/importmap.json`, with the list of modules to preload. Local modules appear as `asset:` plus their logical path, such as `asset:astrology/math_controller.js`, so the map is the same on every machine.
+
+`javascript_jspm_tags` renders that map for Propshaft. Propshaft serves each file under a digested name, so the helper rewrites the map's URLs:
+
+```json
+"tom-select": "https://ga.jspm.io/npm:tom-select@2.4.3/dist/esm/tom-select.complete.js"
+```
+
+becomes
+
+```json
+"tom-select": "/assets/ga.jspm.io/npm/tom-select@2.4.3/dist/esm/tom-select.complete-c479c3ee.js"
+```
+
+A module imports its siblings by their plain names, though. When `tom-select.complete.js` imports `./constants.js`, the browser asks for `/assets/.../constants.js`, which Propshaft doesn't serve. So the rendered map also sends each plain module URL to its digested one:
+
+```json
+"/assets/ga.jspm.io/npm/tom-select@2.4.3/dist/esm/constants.js":
+  "/assets/ga.jspm.io/npm/tom-select@2.4.3/dist/esm/constants-115aef3a.js"
+```
+
+That's a standard import-map feature, so nothing gets rewritten inside the files.
+
+## Compared to
+
+- **importmap-rails** pins one file per package, and you resolve the dependency tree by hand. jspm-rails traces the whole tree.
+- **jsbundling-rails** resolves the tree too, but compiles your JavaScript into a bundle. That means a watcher in development and a build in CI and deploys. And a change to any module busts the cache for the whole bundle. jspm-rails ships the modules as written.
+
+## FAQ
+
+**Why vendor, instead of loading from jspm.io?**
+For the reasons importmap-rails switched to vendoring in [rails/importmap-rails#217](https://github.com/rails/importmap-rails/pull/217). Under HTTP/2, every extra origin costs a connection, so serving from your own costs less. Your app also stops depending on a third party at runtime, and development works offline.
+
+**Do I need npm at all?**
+You need it to install `@jspm/generator`. Beyond that, no: plain jspm packages need nothing in `package.json`.
+
+**Can I use TypeScript or JSX?**
+Not with jspm-rails, which doesn't transpile. Use jsbundling-rails.
+
+**Can I import a stylesheet as a module (`with { type: 'css' }`)?**
+Safari doesn't support CSS module scripts yet, so link stylesheets with `stylesheet_link_tag`.
+
+**Can I have more than one entry point?**
+Not yet. Import everything from `application.js`, dynamically for code only some pages need.
+
+**Can I use it alongside importmap-rails?**
+Use one or the other. Both render the page's import map.
+
+**Does it work on Windows?**
+It's untested there.
+
+## Troubleshooting
+
+**`tracing ./app/javascript/application.js failed`**
+Node printed the reason just above. Usually Node isn't on your `PATH`, or `@jspm/generator` isn't installed: run `npm install --save-dev @jspm/generator`.
+
+**`Propshaft::MissingAssetError` for a file under `ga.jspm.io`**
+`config/importmap.json` names a module that `vendor/jspm` doesn't have. Run `bin/rails jspm:install` and commit both.
+
+**Modules or fonts fail to load with an asset host**
+The asset host must send `Access-Control-Allow-Origin`. See [Deploying](#deploying).
+
+**A package's stylesheet 404s**
+Install the package with npm as a dependency, not a devDependency, and run the install. See [Stylesheets, fonts and images](#stylesheets-fonts-and-images).
+
+## Development
+
+```sh
+bundle install
+npm ci && npx playwright install chromium
+(cd spec/dummy && npm ci) && (cd spec/fixtures/conflicted && npm ci)
+bundle exec rake
+```
+
+The specs install into a dummy Rails app through `bin/rails jspm:install`. Then they drive it in Chromium through Playwright, on one origin and on two, finding elements by their accessible role and name. Any JavaScript error fails the example. So they need network access to jspm.io.
+
+Report security issues privately; see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

data/lib/jspm/assets.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Jspm
+  # The stylesheets, fonts and images of each npm dependency, and where each
+  # one is vendored. devDependencies are build tools, so they stay out.
+  module Assets
+    EXTENSIONS = %w[
+      .avif
+      .css
+      .eot
+      .gif
+      .jpeg
+      .jpg
+      .otf
+      .png
+      .svg
+      .ttf
+      .webp
+      .woff
+      .woff2
+    ].freeze
+    private_constant :EXTENSIONS
+
+    class << self
+      # Each copy is a pair: the file in node_modules, and its vendored path.
+      def copies(lockfile:, root:)
+        lockfile.browser_packages.flat_map { |package| package_copies(package, root) }
+      end
+
+      private
+
+      def package_copies(package, root)
+        package_dir = root.join(package.path)
+        vendor_dir = root.join(Paths::VENDOR, package.name)
+        files =
+          package_dir.glob('**/*').select do |file|
+            EXTENSIONS.include?(file.extname.downcase)
+          end
+        files.map do |file|
+          relative_path = file.relative_path_from(package_dir)
+          [file, vendor_dir.join(relative_path)]
+        end
+      end
+    end
+  end
+end

data/lib/jspm/check.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module Jspm
+  # Traces again without writing anything, and reports whether
+  # config/importmap.json and vendor/jspm match what an install would produce.
+  class Check
+    def self.call(asset_paths:, output:, root:)
+      lockfile = Lockfile.read(root)
+      trace = Trace.call(asset_paths:, lockfile:, root:)
+      new(lockfile:, output:, root:, trace:).call
+    end
+
+    def initialize(lockfile:, output:, root:, trace:)
+      @lockfile = lockfile
+      @output = output
+      @root = root
+      @trace = trace
+    end
+
+    def call
+      written = written?
+      missing = missing_modules
+      stale_assets = stale_asset_paths
+      report('stale', Paths::IMPORT_MAP) unless written
+      missing.each { |path| report('missing', path) }
+      stale_assets.each { |path| report('stale', path) }
+
+      up_to_date = written && missing.empty? && stale_assets.empty?
+      if up_to_date
+        report('ok', 'nothing to install')
+      else
+        report('run', 'bin/rails jspm:install')
+      end
+      up_to_date
+    end
+
+    private
+
+    attr_reader :lockfile, :output, :root, :trace
+
+    def written?
+      import_map_file = root.join(Paths::IMPORT_MAP)
+      import_map_file.exist? && JSON.parse(import_map_file.read) == trace.import_map
+    end
+
+    def stale_asset_paths
+      copies = Assets.copies(lockfile:, root:)
+      stale =
+        copies.reject do |source, target|
+          target.file? && FileUtils.compare_file(source, target)
+        end
+      stale.map { |_source, target| target.relative_path_from(root).to_s }
+    end
+
+    def missing_modules
+      vendored = trace.cdn_urls.map { |url| File.join(Paths::VENDOR, Paths.logical(url)) }
+      vendored.reject { |path| root.join(path).file? }
+    end
+
+    def report(status, message)
+      output.puts(format('%<status>12s  %<message>s', message:, status:))
+    end
+  end
+end

data/lib/jspm/helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Jspm
+  # View helpers for apps whose JavaScript jspm-rails installs.
+  module Helper
+    def javascript_jspm_tags
+      Tags.call(view: self)
+    end
+  end
+end

data/lib/jspm/install.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'net/http'
+
+module Jspm
+  # Vendors every module the trace reaches from jspm.io, copies npm
+  # dependencies' stylesheets, fonts and images, and writes
+  # config/importmap.json.
+  class Install
+    SOURCE_MAP = %r{//# sourceMappingURL=(?<path>\S+\.map)\s*\z}
+    PACKAGE_URL = %r{\Ahttps://ga\.jspm\.io/npm:(?<name>(?:@[^/]+/)?[^@/]+)@(?<version>[^/]+)/}
+    private_constant :PACKAGE_URL, :SOURCE_MAP
+
+    def self.call(asset_paths:, output:, root:)
+      lockfile = Lockfile.read(root)
+      trace = Trace.call(asset_paths:, lockfile:, root:)
+      new(lockfile:, output:, root:, trace:).call
+    end
+
+    def initialize(lockfile:, output:, root:, trace:)
+      @lockfile = lockfile
+      @output = output
+      @root = root
+      @trace = trace
+    end
+
+    def call
+      vendor_dir = root.join(Paths::VENDOR)
+      FileUtils.rm_rf(vendor_dir)
+      cdn = URI(Paths::CDN)
+      cdn_urls = trace.cdn_urls
+      Net::HTTP.start(cdn.host, cdn.port, use_ssl: true) { |http| download_all(http, cdn_urls, vendor_dir) }
+      copies = Assets.copies(lockfile:, root:)
+      copies.each do |source, target|
+        target.dirname.mkpath
+        FileUtils.cp(source, target)
+      end
+      root.join(Paths::IMPORT_MAP).write("#{JSON.pretty_generate(trace.import_map)}\n")
+
+      report('traced', Paths::ENTRY_PATH)
+      report('vendored', "#{cdn_urls.size} modules from ga.jspm.io")
+      report('copied', "#{copies.size} assets from node_modules")
+      report('wrote', Paths::IMPORT_MAP)
+      warn_about_versions
+    end
+
+    private
+
+    attr_reader :lockfile, :output, :root, :trace
+
+    def download_all(http, urls, vendor_dir)
+      urls.each { |url| download(http, url, vendor_dir) }
+    end
+
+    def download(http, url, vendor_dir)
+      body = http.get(URI(url).path).tap(&:value).body
+      file = vendor_dir.join(Paths.logical(url))
+      file.dirname.mkpath
+      file.binwrite(body)
+      source_maps = body.scan(SOURCE_MAP).map { |(path)| URI.join(url, path).to_s }
+      download_all(http, source_maps, vendor_dir)
+    end
+
+    def warn_about_versions
+      packages =
+        trace.urls.grep(PACKAGE_URL) do |url|
+          url.match(PACKAGE_URL).values_at(:name, :version)
+        end
+      traced = packages.sort.to_h
+      versions_by_name =
+        traced.to_h { |name, version| [name, (lockfile.nested_versions(name) | [version]).sort] }
+      conflicts = versions_by_name.select { |_name, versions| versions.many? }
+      conflicts.each do |name, versions|
+        report(
+          'warn',
+          "#{name}: package-lock.json has #{versions.join(' and ')}, " \
+          "and the import map uses #{traced.fetch(name)} everywhere"
+        )
+      end
+    end
+
+    def report(status, message)
+      output.puts(format('%<status>12s  %<message>s', message:, status:))
+    end
+  end
+end

data/lib/jspm/local_modules.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Jspm
+  # The modules Propshaft serves from the app and from engines. Each one is
+  # importable by its asset name without the extension, the way importmap-rails
+  # pins work: 'controllers/hello_controller', or 'controllers' for
+  # controllers/index.js.
+  #
+  # config/importmap.json names these files as `asset:` plus their logical
+  # path, so the map reads the same on every machine.
+  class LocalModules
+    EXTENSIONS = %w[.js .mjs].freeze
+    SCHEME = 'asset:'
+    private_constant :EXTENSIONS, :SCHEME
+
+    LocalModule =
+      Data.define(:logical_path, :path) do
+        def asset_name
+          "#{SCHEME}#{logical_path}"
+        end
+
+        def pins
+          name = logical_path.delete_suffix(File.extname(logical_path))
+          index = name.delete_suffix('/index') if name.end_with?('/index')
+          [name, *index].map { |pin| [pin, path] }
+        end
+      end
+    private_constant :LocalModule
+
+    class << self
+      def find(asset_paths:)
+        new(modules: asset_paths.flat_map { |directory| directory_modules(directory) })
+      end
+
+      private
+
+      def directory_modules(directory)
+        files = directory.glob('**/*').select { |file| EXTENSIONS.include?(file.extname) }
+        files.map do |file|
+          logical_path = file.relative_path_from(directory).to_s
+          LocalModule.new(logical_path:, path: file.to_s)
+        end
+      end
+    end
+
+    def initialize(modules:)
+      @modules = modules
+    end
+
+    def pins
+      modules.flat_map(&:pins).to_h
+    end
+
+    # A local file becomes its asset name. A local directory, the key of a
+    # scope, becomes the asset root, where every local module is served. A
+    # jspm.io URL stays as it is.
+    def localize(target)
+      case target
+      when %r{\A/.*/\z} then SCHEME
+      when %r{\A/} then modules_by_path.fetch(target).asset_name
+      else target
+      end
+    end
+
+    private
+
+    attr_reader :modules
+
+    def modules_by_path
+      modules.to_h { |local_module| [local_module.path, local_module] }
+    end
+  end
+end

data/lib/jspm/lockfile.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Jspm
+  # The packages npm installed, as package-lock.json records them.
+  class Lockfile
+    Package =
+      Data.define(:dev, :name, :path, :top_level, :version) do
+        def browser?
+          top_level && !dev
+        end
+
+        def resolution
+          [name, version]
+        end
+
+        def nested?(other_name)
+          !top_level && name == other_name
+        end
+      end
+    private_constant :Package
+
+    def self.read(root)
+      json = JSON.parse(root.join('package-lock.json').read)
+      installed = json.fetch('packages').reject { |path, _package| path.empty? }
+      packages =
+        installed.map do |path, package|
+          name = path.split('node_modules/').last
+          top_level = path.scan('node_modules/').one?
+          version = package.fetch('version')
+          dev = package.fetch('dev', false)
+          Package.new(dev:, name:, path:, top_level:, version:)
+        end
+      new(packages:)
+    end
+
+    def initialize(packages:)
+      @packages = packages
+    end
+
+    def resolutions
+      packages.select(&:top_level).to_h(&:resolution)
+    end
+
+    def browser_packages
+      packages.select(&:browser?)
+    end
+
+    def nested_versions(name)
+      nested = packages.select { |package| package.nested?(name) }
+      nested.map(&:version)
+    end
+
+    private
+
+    attr_reader :packages
+  end
+end

data/lib/jspm/paths.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jspm
+  # Translates the URLs in config/importmap.json into Propshaft logical paths.
+  #
+  # jspm.io files are vendored under vendor/jspm/ga.jspm.io/npm/, and local
+  # modules are written as `asset:` plus their logical path.
+  module Paths
+    CDN = 'https://ga.jspm.io/'
+    ENTRY = 'application.js'
+    LOCAL = './app/javascript/'
+    ENTRY_PATH = "#{LOCAL}#{ENTRY}".freeze
+    IMPORT_MAP = 'config/importmap.json'
+    VENDOR = 'vendor/jspm'
+    public_constant :CDN, :ENTRY, :ENTRY_PATH, :IMPORT_MAP, :LOCAL, :VENDOR
+
+    def self.logical(url)
+      return url.delete_prefix('https://').sub('/npm:', '/npm/') if url.start_with?(CDN)
+
+      url.delete_prefix('asset:')
+    end
+  end
+end

data/lib/jspm/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Jspm
+  # Serves the app's modules and the vendored dependencies through Propshaft.
+  class Railtie < Rails::Railtie
+    # jspm.io publishes many packages' modules as .mjs, and browsers only run
+    # a module script served with a JavaScript MIME type.
+    initializer 'jspm.mime_type' do
+      Mime::Type.register_alias('text/javascript', :mjs)
+    end
+
+    initializer 'jspm.assets' do |app|
+      app.config.assets.paths.push(app.root.join('app/javascript'), app.root.join('vendor/jspm'))
+    end
+
+    initializer 'jspm.helper' do
+      ActiveSupport.on_load(:action_view) { include Helper }
+    end
+
+    rake_tasks do
+      load File.expand_path('../tasks/jspm.rake', __dir__)
+    end
+  end
+end

data/lib/jspm/tags.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Jspm
+  # Renders config/importmap.json for the browser.
+  #
+  # Propshaft serves every file under a digested name, but a module's relative
+  # imports name its siblings undigested. So the rendered map also sends each
+  # undigested module URL to its digested one.
+  class Tags
+    MODULE_EXTENSIONS = %w[.css .js .mjs].freeze
+    private_constant :MODULE_EXTENSIONS
+
+    def self.call(view:)
+      import_map = JSON.parse(Rails.root.join(Paths::IMPORT_MAP).read)
+      load_path = Rails.application.assets.load_path
+      entry_url = view.asset_path(Paths::ENTRY)
+      digested_entry = load_path.find(Paths::ENTRY).digested_path.to_s
+      prefix = entry_url.delete_suffix(digested_entry)
+      new(entry_url:, import_map:, load_path:, prefix:, view:).call
+    end
+
+    def initialize(entry_url:, import_map:, load_path:, prefix:, view:)
+      @entry_url = entry_url
+      @import_map = import_map
+      @load_path = load_path
+      @prefix = prefix
+      @view = view
+    end
+
+    def call
+      nonce = view.content_security_policy_nonce
+      tag = view.tag
+      imports = asset_urls(import_map.fetch('imports'))
+      json = ERB::Util.json_escape(JSON.generate(imports: imports.merge(digests), scopes:))
+      preloads =
+        import_map.fetch('preload').map do |url|
+          href = asset_url(url)
+          tag.link(href:, nonce:, rel: 'modulepreload')
+        end
+      import_map_tag = tag.script(
+        json.html_safe,
+        data: { turbo_track: 'reload' },
+        nonce:,
+        type: 'importmap'
+      )
+      entry_tag = tag.script(nonce:, src: entry_url, type: 'module')
+      view.safe_join([import_map_tag, *preloads, entry_tag], "\n")
+    end
+
+    private
+
+    attr_reader :entry_url, :import_map, :load_path, :prefix, :view
+
+    def scopes
+      import_map.fetch('scopes', {}).to_h do |scope, specifiers|
+        ["#{prefix}#{Paths.logical(scope)}", asset_urls(specifiers)]
+      end
+    end
+
+    def asset_urls(specifiers)
+      specifiers.transform_values { |url| asset_url(url) }
+    end
+
+    def digests
+      paths = load_path.assets.map { |asset| [asset.logical_path, asset.digested_path] }
+      modules =
+        paths.select do |logical_path, _digested_path|
+          MODULE_EXTENSIONS.include?(logical_path.extname)
+        end
+      modules.to_h do |logical_path, digested_path|
+        ["#{prefix}#{logical_path}", "#{prefix}#{digested_path}"]
+      end
+    end
+
+    def asset_url(url)
+      logical_path = Paths.logical(url)
+      view.asset_path(logical_path)
+    end
+  end
+end

data/lib/jspm/trace.mjs

@@ -0,0 +1,50 @@
+// Traces the app's entry module with @jspm/generator and prints the result as
+// JSON. The generator is resolved from the app's own node_modules, so the app
+// pins its version in package-lock.json like any other dependency.
+//
+// Ruby speaks file paths and jspm speaks URLs, so local files cross this
+// boundary as absolute paths.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const { entry, inputMap, resolutions, root } = JSON.parse(readFileSync(0, 'utf8'));
+const rootUrl = pathToFileURL(`${root}/`);
+const generatorPath = createRequire(rootUrl).resolve('@jspm/generator');
+const { Generator } = await import(pathToFileURL(generatorPath));
+
+const toUrl = (target) => (target.startsWith('/') ? pathToFileURL(target).href : target);
+const toPath = (target) => {
+  const url = new URL(target, rootUrl);
+  return url.protocol === 'file:' ? fileURLToPath(url) : url.href;
+};
+const mapEntries = (specifiers, convert) =>
+  Object.fromEntries(Object.entries(specifiers).map(([name, target]) => [name, convert(target)]));
+const mapScopes = (scopes, convert) =>
+  Object.fromEntries(
+    Object.entries(scopes).map(([scope, specifiers]) => [convert(scope), mapEntries(specifiers, convert)])
+  );
+
+const generator = new Generator({
+  baseUrl: rootUrl,
+  combineSubpaths: true,
+  defaultProvider: 'jspm.io',
+  env: ['browser', 'module', 'production'],
+  flattenScopes: true,
+  inputMap: { imports: mapEntries(inputMap.imports, toUrl), scopes: mapScopes(inputMap.scopes, toUrl) },
+  inputPins: false,
+  mapUrl: rootUrl,
+  resolutions,
+});
+
+const { dynamicDeps, staticDeps } = await generator.link(entry);
+const map = generator.getMap();
+
+process.stdout.write(
+  JSON.stringify({
+    dynamicDeps: dynamicDeps.map(toPath),
+    imports: mapEntries(map.imports ?? {}, toPath),
+    scopes: mapScopes(map.scopes ?? {}, toPath),
+    staticDeps: staticDeps.map(toPath),
+  })
+);

data/lib/jspm/trace.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module Jspm
+  class Error < StandardError
+  end
+
+  # What jspm's generator finds when it traces the app's entry module. The
+  # previous import map locks versions, as in jspm, and package-lock.json's
+  # versions override it. Modules on the asset path are importable by name.
+  Trace =
+    Data.define(:import_map, :urls) do
+      def self.call(asset_paths:, lockfile:, root:)
+        vendor_dir = root.join(Paths::VENDOR)
+        pathnames = asset_paths.map { |path| Pathname(path) }
+        module_paths = pathnames.reject { |path| path == vendor_dir }
+        local_modules = LocalModules.find(asset_paths: module_paths)
+        input = JSON.generate(
+          entry: Paths::ENTRY_PATH,
+          inputMap: { imports: locked_versions(root).merge(local_modules.pins), scopes: {} },
+          resolutions: lockfile.resolutions,
+          root: root.to_s
+        )
+        script = File.expand_path('trace.mjs', __dir__)
+        json, status = Open3.capture2('node', script, stdin_data: input)
+        raise(Error, "tracing #{Paths::ENTRY_PATH} failed") unless status.success?
+
+        from_trace(JSON.parse(json), local_modules)
+      end
+
+      # Every jspm.io module the previous map named, keyed by its specifier.
+      # jspm keeps the versions of packages it finds there.
+      def self.locked_versions(root)
+        import_map_file = root.join(Paths::IMPORT_MAP)
+        return {} unless import_map_file.exist?
+
+        import_map = JSON.parse(import_map_file.read)
+        specifiers = [import_map.fetch('imports'), *import_map.fetch('scopes', {}).values]
+        specifiers.reduce(:merge).select { |_specifier, url| url.start_with?(Paths::CDN) }
+      end
+
+      def self.from_trace(result, local_modules)
+        localize = local_modules.method(:localize)
+        imports = result.fetch('imports').transform_values(&localize)
+        scopes = localize_scopes(result.fetch('scopes'), localize)
+        static = result.fetch('staticDeps').map(&localize)
+        dynamic = result.fetch('dynamicDeps').map(&localize)
+        new(
+          import_map: { 'imports' => imports, 'scopes' => scopes, 'preload' => static },
+          urls: static + dynamic
+        )
+      end
+
+      # Every local directory becomes the asset root, so their scopes merge.
+      def self.localize_scopes(scopes, localize)
+        pairs =
+          scopes.map do |scope, specifiers|
+            [localize.call(scope), specifiers.transform_values(&localize)]
+          end
+        grouped = pairs.group_by(&:first)
+        grouped.transform_values { |entries| entries.map(&:last).reduce(:merge) }
+      end
+
+      def cdn_urls
+        urls.select { |url| url.start_with?(Paths::CDN) }
+      end
+    end
+  public_constant :Trace
+end

data/lib/jspm/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Jspm
+  VERSION = '0.1.0'
+  public_constant :VERSION
+end

data/lib/jspm-rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'jspm/assets'
+require 'jspm/check'
+require 'jspm/helper'
+require 'jspm/install'
+require 'jspm/local_modules'
+require 'jspm/lockfile'
+require 'jspm/paths'
+require 'jspm/railtie'
+require 'jspm/tags'
+require 'jspm/trace'
+require 'jspm/version'

data/lib/tasks/jspm.rake

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+namespace :jspm do
+  desc 'Vendor what app/javascript/application.js imports, and write config/importmap.json'
+  task install: :environment do
+    Jspm::Install.call(
+      asset_paths: Rails.application.config.assets.paths,
+      output: $stdout,
+      root: Rails.root
+    )
+  end
+
+  desc 'Fail if config/importmap.json or vendor/jspm is out of date'
+  task check: :environment do
+    passed = Jspm::Check.call(
+      asset_paths: Rails.application.config.assets.paths,
+      output: $stdout,
+      root: Rails.root
+    )
+    abort unless passed
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: jspm-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Clay Shentrup
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: propshaft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: |
+  Traces app/javascript/application.js with jspm, vendors every module it reaches from jspm.io,
+  and serves them through Propshaft. Versions lock in jspm's import map, or in package-lock.json for
+  packages installed with npm. No bundler, no build step.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/jspm-rails.rb
+- lib/jspm/assets.rb
+- lib/jspm/check.rb
+- lib/jspm/helper.rb
+- lib/jspm/install.rb
+- lib/jspm/local_modules.rb
+- lib/jspm/lockfile.rb
+- lib/jspm/paths.rb
+- lib/jspm/railtie.rb
+- lib/jspm/tags.rb
+- lib/jspm/trace.mjs
+- lib/jspm/trace.rb
+- lib/jspm/version.rb
+- lib/tasks/jspm.rake
+homepage: https://github.com/ClayShentrup/jspm-rails
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/ClayShentrup/jspm-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/ClayShentrup/jspm-rails
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Import maps for Rails, built by jspm
+test_files: []