hanami-importmap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0cf57753c3e8efea348d6763d372617262b055054e1158cbf339a48f10746dd7
+  data.tar.gz: 957405604785d2f08a4c7a7e9a318372423d0de69dc99fe7ad3c3055889633b0
+SHA512:
+  metadata.gz: bc2c759e8d900456f46bd75f56c790bd8306a473c528f2a290c4d437ddfdc2cc6dc8116d39625f174f86d373375768e3acb8ab7477452ac53d874c79f99e5334
+  data.tar.gz: 37519ebf5df7a16f7de8365ec82946973af0549930bf4b005e211b5a1a36fdc32dbbac1555345e3966644357e92baf43831732c0b074d907a771f92a0016bdd0

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Pure-Ruby bundler for hanami-assets, replacing `hanami assets compile` and `hanami assets watch`.
+- `config/importmap.rb` with `pin` and `pin_all_from`, per app and per slice.
+- `javascript_importmap_tags`, with subresource integrity and CSP nonces.
+- `hanami importmap install`, `pin`, `unpin` and `json`.
+- Hooks: `hanami install` switches a new app to import maps; `hanami generate slice` gives new slices their own import map.

data/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 Andrea Fomera
+
+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,186 @@
+# hanami-importmap
+
+Import maps for [Hanami](https://hanamirb.org). Ship JavaScript as ES modules, with no Node, no
+npm, and no bundler. This is the Hanami counterpart to
+[importmap-rails](https://github.com/rails/importmap-rails).
+
+```ruby
+# config/importmap.rb
+pin "app"
+pin "@hotwired/turbo", to: "@hotwired--turbo.js"
+pin "@hotwired/stimulus", to: "@hotwired--stimulus.js"
+pin_all_from "js/controllers", under: "controllers"
+```
+
+```erb
+<%# app/templates/layouts/app.html.erb %>
+<head>
+  <%= stylesheet_tag "app" %>
+  <%= javascript_importmap_tags %>
+</head>
+```
+
+## How it fits into Hanami
+
+hanami-importmap is a **bundler for hanami-assets**, written in Ruby. It does not replace
+hanami-assets. It replaces `hanami assets compile` and `hanami assets watch`, and writes the same
+`public/assets/**/assets.json` manifests that the esbuild bundler writes, following the
+[hanami-assets bundler spec](https://github.com/hanami/hanami-assets/blob/main/SPEC.md).
+
+Everything that reads those manifests keeps working as before:
+
+- `javascript_tag`, `stylesheet_tag`, `image_tag`, `favicon_tag` and `asset_url`
+- `config.assets.base_url` (CDNs) and `config.assets.subresource_integrity`
+- static file serving
+- slices, which each get their own assets and import map
+- `bin/dev`
+
+## Installation
+
+Requires Hanami 2.3+ with hanami-assets. It is built and tested against Hanami's main branches.
+
+Add the gem to the `:cli` group as well as the default group. The `hanami` CLI only loads the
+`:cli` group, and that's how the gem takes over the assets commands.
+
+```ruby
+gem "hanami-importmap", group: [:default, :cli]
+```
+
+Then switch the app over:
+
+```sh
+bundle install
+bundle exec hanami install    # or `bundle exec hanami importmap install`
+```
+
+For a new app, run `hanami new bookshelf`, add the gem, and run those two commands. `hanami install`
+switches the app to import maps the first time it runs with the gem bundled, when there's no
+`config/importmap.rb` yet; later runs leave the app alone. `hanami new` has no option for this,
+and a gem can't add one, because Hanami loads plugins from the app's Gemfile and the app doesn't
+exist yet.
+
+`install` makes these changes:
+
+- **`config/app.rb`**
+  - Requires `hanami/importmap`.
+  - Adds `'nonce'` to the Content Security Policy's `script-src` (see below).
+- **`config/importmap.rb`:** creates it, with `pin "app"`.
+- **`app/assets/js/app.js`:** removes `import "../css/app.css"`. That import only works with
+  esbuild; the layout already loads the CSS with `stylesheet_tag`.
+- **The layout:** swaps `javascript_tag "app"` for `javascript_importmap_tags` in the `<head>`.
+- **Node files:**
+  - Removes `config/assets.js`, `package.json`, `package-lock.json`, and `npm install` from
+    `bin/setup`.
+  - Files you've customized are kept, and the command says so.
+  - Delete `node_modules/` yourself.
+
+`hanami generate slice` gets the same treatment automatically: the new slice gets its own
+`config/importmap.rb` and `javascript_importmap_tags`. For a slice that existed before you added
+the gem, run `bundle exec hanami importmap install --slice=admin`.
+
+## Pinning packages
+
+```sh
+bundle exec hanami importmap pin @hotwired/stimulus @hotwired/turbo
+bundle exec hanami importmap pin canvas-confetti --slice=admin
+bundle exec hanami importmap pin lodash@4.17.21 --no-preload
+bundle exec hanami importmap unpin lodash
+```
+
+`pin` resolves packages and their dependencies with the [jspm.io](https://jspm.org) generator. It
+downloads them into `app/assets/vendor/` (or `slices/<name>/assets/vendor/`) and adds the `pin`
+lines. Vendored files are your assets: they're fingerprinted, served from your own origin, and
+committed to your repo.
+
+`bundle exec hanami importmap json [--slice=admin]` prints the import map from the last build.
+
+## The DSL
+
+The `to:` value of a pin is an **asset name**, the same name you'd give to `javascript_tag`. Asset
+names are paths under the assets directory, with the first directory removed:
+
+| File | Asset name |
+|---|---|
+| `app/assets/js/app.js` | `app.js` |
+| `app/assets/js/controllers/hello_controller.js` | `controllers/hello_controller.js` |
+| `app/assets/vendor/@hotwired--turbo.js` | `@hotwired--turbo.js` |
+| `app/assets/images/logo.png` | `logo.png` |
+
+```ruby
+pin "app"                                    # to: "app.js"
+pin "@hotwired/turbo", to: "@hotwired--turbo.js"
+pin "lodash", to: "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js", preload: false,
+  integrity: "sha384-…"                      # a URL, not vendored
+pin_all_from "js/controllers", under: "controllers"
+# js/controllers/hello_controller.js → "controllers/hello_controller"
+# js/controllers/index.js            → "controllers"
+```
+
+Pins are preloaded (`<link rel="modulepreload">`) unless you pass `preload: false`.
+
+If a pin doesn't match an asset, `hanami assets compile` fails and names the pin. You won't find
+out in the browser.
+
+### Slices
+
+- A slice with its own `slices/<name>/config/importmap.rb` gets its own map, built from its own
+  assets.
+- A slice without one uses the app's `config/importmap.rb`, resolved against the slice's assets.
+  This is the same fallback hanami-assets uses for `config/assets.js`.
+- `javascript_importmap_tags` always renders the current slice's map.
+
+## What compile and watch do
+
+- **`hanami assets compile`**
+  - Copies every file under each assets directory to `public/assets/`, with the content digest
+    in the filename: `app-F5D98970.js`.
+  - Rewrites CSS `url(...)` and `@import` references to other assets to point at their output
+    paths.
+  - Writes `assets.json`, plus `importmap.json` from your `config/importmap.rb`.
+  - Includes `sri` digests when `config.assets.subresource_integrity` is set. These go into the
+    import map's `integrity` section too, so the browser checks every module, not just the entry
+    point.
+- **`hanami assets watch`**
+  - Builds with stable filenames.
+  - Rebuilds a slice when a file in its assets directory or its `importmap.rb` changes.
+  - The running server picks up new maps without a restart.
+
+There's no transpiling and no minification. TypeScript, JSX and Sass files raise an error that
+points you at hanami-assets-js.
+
+## Content Security Policy
+
+Hanami's default policy is `script-src 'self'`, which blocks inline scripts. Browsers don't support
+external import maps, so the map has to be an inline `<script type="importmap">`.
+
+`install` adds `'nonce'` to `script-src`. Hanami then adds its nonce middleware, and
+`javascript_importmap_tags` puts the request's nonce on its tags:
+
+```ruby
+config.actions.content_security_policy[:script_src] += " 'nonce'"
+```
+
+Pass `nonce: false` to leave it off, or `nonce: "…"` to set it yourself.
+
+## Caveats
+
+- **Use bare specifiers between your own modules.** For example, write
+  `import "controllers/hello_controller"`, not `import "./hello_controller.js"`. Fingerprinted
+  filenames break relative imports. importmap-rails has the same rule, and `pin_all_from` exists
+  for this.
+- **Pick one bundler per app.** The override covers the whole app, so you can't use esbuild for one
+  slice and import maps for another.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+The specs include an end-to-end run of the real `hanami` CLI in a temporary app. See
+[hanami-importmap-example](https://github.com/afomera/hanami-importmap-example) for a full app.
+
+## License
+
+MIT

data/lib/hanami/importmap/cli/assets.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "hanami/cli"
+require "hanami/assets"
+require "hanami/cli/commands/app/assets"
+require_relative "../compiler"
+
+module Hanami
+  module Importmap
+    module CLI
+      # Where one app's or slice's assets come from and go to.
+      #
+      # @api private
+      Target = Data.define(:slice, :source, :destination, :public_dir, :importmap_path) do
+        # @api private
+        def self.for(slice)
+          app_root = slice.app.root
+          app = slice.eql?(slice.app)
+
+          new(
+            slice:,
+            source: app ? app_root.join("app", "assets") : slice.root.join("assets"),
+            destination: app_root.join("public", "assets", Hanami::Assets.public_assets_dir(slice).to_s),
+            public_dir: app_root.join("public"),
+            # A slice without its own import map uses the app's, resolved against the slice's assets,
+            # the same way a slice without a config/assets.js uses the app's.
+            importmap_path: [slice.root.join("config", "importmap.rb"), app_root.join("config", "importmap.rb")]
+              .uniq.find(&:file?)
+          )
+        end
+
+        def name = slice.slice_name.to_s
+
+        def compiler(**)
+          Compiler.new(source:, destination:, public_dir:, importmap_path:, **)
+        end
+      end
+
+      # Shared behaviour for the assets commands, which run the {Compiler} in-process for each slice
+      # instead of spawning `node config/assets.js`.
+      #
+      # @api private
+      module AssetsCommand
+        private
+
+        def targets
+          slices_with_assets.map { Target.for(_1) }
+        end
+
+        def build(target, **)
+          result = target.compiler(**).call
+          pins = result.importmap&.fetch("pins")&.length
+          map_note = pins ? " and import map (#{count(pins, "pin")})" : ""
+          stdout.puts "[#{target.name}] Built #{count(result.manifest.length, "asset")}#{map_note} " \
+            "into #{target.destination.relative_path_from(target.slice.app.root)}/"
+          true
+        rescue Importmap::Error => exception
+          stderr.puts "[#{target.name}] #{exception.message}"
+          false
+        end
+
+        def count(number, noun) = "#{number} #{noun}#{"s" unless number == 1}"
+      end
+
+      # `hanami assets compile`, without Node.
+      #
+      # @api private
+      class Compile < Hanami::CLI::Commands::App::Assets::Compile
+        include AssetsCommand
+
+        desc "Compile assets for deployments (hanami-importmap)"
+
+        def call(**)
+          all = targets
+          return stdout.puts("No assets found.") if all.empty?
+
+          results = all.map { build(_1, fingerprint: true, sri: config.subresource_integrity) }
+          raise Hanami::CLI::Error, "Assets compilation failed" unless results.all?
+        end
+      end
+
+      # `hanami assets watch`, without Node.
+      #
+      # Builds with stable filenames, then rebuilds a slice whenever a file under its assets
+      # directory or its `config/importmap.rb` changes. Build errors are printed and watching
+      # continues.
+      #
+      # @api private
+      class Watch < Hanami::CLI::Commands::App::Assets::Watch
+        include AssetsCommand
+
+        desc "Start assets watch mode (hanami-importmap)"
+
+        def call(**)
+          slices = slices_with_assets
+          return stdout.puts("No assets found.") if slices.empty?
+
+          # Stream output line by line, including when run under `hanami dev` without a TTY.
+          stdout.sync = true if stdout.respond_to?(:sync=)
+
+          slices.each { build(Target.for(_1), fingerprint: false) }
+
+          require "listen"
+          listeners = [
+            listen(slices.map { Target.for(_1).source }) { |paths| rebuild(slices, paths) },
+            listen(config_dirs(slices), only: /\Aimportmap\.rb\z/) { |paths| rebuild(slices, paths) }
+          ].compact
+          listeners.each(&:start)
+          stdout.puts "Watching for asset changes..."
+
+          wait_for_interrupt
+          listeners.each(&:stop)
+        end
+
+        private
+
+        def listen(dirs, **options, &block)
+          dirs = dirs.select(&:directory?).map { File.realpath(_1) }.uniq
+          return if dirs.empty?
+
+          Listen.to(*dirs, **options) do |modified, added, removed|
+            block.call((modified + added + removed).uniq)
+          end
+        end
+
+        def config_dirs(slices)
+          slices.flat_map { [_1.root.join("config"), _1.app.root.join("config")] }
+        end
+
+        def rebuild(slices, paths)
+          slices.each do |slice|
+            target = Target.for(slice) # re-resolved, since a slice may gain or lose its own import map
+            source = target.source.directory? ? File.realpath(target.source) : target.source.to_s
+            map = target.importmap_path && File.realpath(target.importmap_path)
+
+            next unless paths.any? { _1.start_with?("#{source}/") || _1 == map || File.basename(_1) == "importmap.rb" }
+
+            build(target, fingerprint: false)
+          end
+        end
+
+        def wait_for_interrupt
+          queue = Thread::Queue.new
+          %w[INT TERM].each { |signal| Signal.trap(signal) { queue << signal } }
+          queue.pop
+        end
+      end
+    end
+  end
+end

data/lib/hanami/importmap/cli/hooks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "hanami/cli"
+require_relative "install"
+
+module Hanami
+  module Importmap
+    module CLI
+      # Callbacks on hanami-cli's own commands, so import maps are set up without extra steps.
+      #
+      # @api private
+      module Hooks
+        # After `hanami install`: switch the app to import maps the first time it runs with this gem
+        # bundled, so adding the gem and running `hanami install` is enough.
+        class AfterInstall < Hanami::CLI::Command
+          def call(*, **)
+            return if Pathname("config/importmap.rb").exist?
+
+            Install.new(stdout:, stderr:, fs:).call
+          end
+        end
+
+        # After `hanami generate slice`: give the new slice its own import map, in place of the
+        # esbuild-style `javascript_tag` and CSS import the slice generator writes.
+        class AfterGenerateSlice < Hanami::CLI::Command
+          def call(name:, **)
+            slice = Dry::Inflector.new.underscore(name)
+            return unless Pathname("config/importmap.rb").exist?
+            return unless Pathname("slices").join(slice, "assets").directory?
+            return if Pathname("slices").join(slice, "config", "importmap.rb").exist?
+
+            Install.new(stdout:, stderr:, fs:).call(slice:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/importmap/cli/importmap.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require "hanami/cli"
+require_relative "../packager"
+require_relative "../resolver"
+require_relative "assets"
+
+module Hanami
+  module Importmap
+    module CLI
+      # Paths for the app or a slice, without booting the app.
+      #
+      # @api private
+      module SlicePaths
+        private
+
+        def slice_root(slice)
+          return Pathname(".") unless slice
+
+          # A plain inflector, so these commands don't boot the app.
+          root = Pathname("slices").join(Dry::Inflector.new.underscore(slice))
+          raise Hanami::CLI::MissingSliceError.new(slice) unless root.directory?
+
+          root
+        end
+
+        def assets_dir(slice)
+          slice ? slice_root(slice).join("assets") : Pathname("app/assets")
+        end
+
+        def importmap_path(slice)
+          slice_root(slice).join("config", "importmap.rb")
+        end
+
+        def packager(slice)
+          Packager.new(importmap_path: importmap_path(slice), vendor_path: assets_dir(slice).join("vendor"))
+        end
+      end
+
+      # `hanami importmap pin`
+      #
+      # @api private
+      class Pin < Hanami::CLI::Commands::App::Command
+        include SlicePaths
+
+        desc "Pin npm packages, downloading them into the assets vendor directory"
+
+        argument :packages, type: :array, required: true, desc: "Package names, optionally with versions (e.g. lodash@4.17.21)"
+        option :slice, required: false, desc: "Slice name"
+        option :from, required: false, default: "jspm", desc: "CDN to resolve packages with (jspm, jsdelivr, unpkg)"
+        option :preload, type: :flag, default: true, desc: "Preload the pinned modules"
+
+        example [
+          "@hotwired/stimulus                 # Pin Stimulus for the app",
+          "@hotwired/turbo --slice=admin      # Pin Turbo for the admin slice",
+          "lodash@4.17.21 --no-preload        # Pin a specific version, without preloading"
+        ]
+
+        def call(packages:, slice: nil, from: "jspm", preload: true, **)
+          packager = packager(slice)
+          imports = packager.import(*packages, from:)
+
+          unless imports
+            raise Hanami::CLI::Error, "Couldn't find #{packages.join(", ")} on #{from}"
+          end
+
+          create_importmap(slice) unless packager.importmap_path.file?
+
+          imports.each do |package, url|
+            path = packager.vendored_path(package)
+            stdout.puts %(Pinning "#{package}" to #{path} via download from #{url})
+            packager.download(package, url)
+            packager.pin(package, url, preload:)
+          end
+        rescue Importmap::Error => exception
+          raise Hanami::CLI::Error, exception.message
+        end
+
+        private
+
+        # A slice's own import map replaces the app's, so start it with the slice's entry point.
+        def create_importmap(slice)
+          path = importmap_path(slice)
+          entry = assets_dir(slice).join("js", "app.js").file? ? %(\npin "app"\n) : ""
+          fs.create(path.to_s, Packager::IMPORTMAP_HEADER + entry)
+
+          if slice && Pathname("config/importmap.rb").file?
+            stdout.puts "The #{slice} slice now uses #{path} instead of config/importmap.rb."
+          end
+        end
+      end
+
+      # `hanami importmap unpin`
+      #
+      # @api private
+      class Unpin < Hanami::CLI::Commands::App::Command
+        include SlicePaths
+
+        desc "Unpin packages and delete their vendored files"
+
+        argument :packages, type: :array, required: true, desc: "Package names"
+        option :slice, required: false, desc: "Slice name"
+
+        def call(packages:, slice: nil, **)
+          packager = packager(slice)
+
+          packages.each do |package|
+            if packager.remove(package)
+              stdout.puts %(Unpinned and removed "#{package}")
+            else
+              stderr.puts %("#{package}" isn't pinned in #{packager.importmap_path})
+            end
+          end
+        end
+      end
+
+      # `hanami importmap json`
+      #
+      # @api private
+      class Json < Hanami::CLI::Commands::App::Command
+        desc "Print the import map, as built by the last `hanami assets compile` or `watch`"
+
+        option :slice, required: false, desc: "Slice name"
+
+        def call(slice: nil, **)
+          target_slice = slice ? app.slices[inflector.underscore(slice).to_sym] : app
+          target = Target.for(target_slice)
+          assets = Hanami::Assets.new(config: target_slice.config.assets, root: target.destination)
+          map = Resolver.new(assets, target.destination).call
+
+          stdout.puts JSON.pretty_generate(map.to_h.merge("preload" => map.preloads))
+        rescue Importmap::Error => exception
+          raise Hanami::CLI::Error, exception.message
+        end
+      end
+    end
+  end
+end