importmap-rails 0.8.0 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ff9e12c3e3daaf05a7de52415d5147fc030efd2ad0cd170eb60a13c0227bb72
-  data.tar.gz: '09d07386cd7f80d6f34d369e530276125e6a5361577896bc847d7968a9f158a6'
+  metadata.gz: e86788c54e7b80120cf17b2df4f51a02f03e8b40356bb2f8abad069639b763a0
+  data.tar.gz: 4e29f8b3e0cacb49f7d379b2536e736acb015f2b9b55a7fdfa97cfb83ccdf916
 SHA512:
-  metadata.gz: 5be65a22e79a2d7bff6b317d1a162dbdc9be2f0fb05449c7675a6c9583a2b578e2e07265bf9fefa1a404a92053dd02f019d705b5b2793184f5e35f28b48a1235
-  data.tar.gz: 32875269eb69d4b1fed15d6d93831dae419354b13e46b2a0edb26b041b403f6e77f4f95169955aa8cda540c8d3d253f49ab0fd2a1a6b8b43e8313a947943ae12
+  metadata.gz: 48ebde452587115deed3ab2f6a2dbcc777eb15bde84feb76cc77d12e884f22557a6131c584e60a4cfcb19a031e131f83fcc78a7fbfc21dbeb7625543d40f7600
+  data.tar.gz: d5f5992507d837c9de40bc88af8776c73150a6fbb628264b96dd6895ee50eb5692776a28f4ff9239e90894a803a59617f370c213a96beacec67a2a0dcc31689a

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Basecamp
+Copyright (c) 2022 Basecamp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,169 +1,269 @@
 # Importmap for Rails
 
-[Import maps](https://github.com/WICG/import-maps) let you import JavaScript modules using logical names that map to versioned/digested files – directly from the browser. So you can [build modern JavaScript applications using JavaScript libraries made for ESM without the need for transpiling or bundling](https://world.hey.com/dhh/modern-web-apps-without-javascript-bundling-or-transpiling-a20f2755).This frees you from needing Webpack, Yarn, npm, or any other part of the JavaScript toolchain. All you need is the asset pipeline that's already included in Rails.
+[Import maps](https://github.com/WICG/import-maps) let you import JavaScript modules using logical names that map to versioned/digested files – directly from the browser. So you can [build modern JavaScript applications using JavaScript libraries made for ES modules (ESM) without the need for transpiling or bundling](https://world.hey.com/dhh/modern-web-apps-without-javascript-bundling-or-transpiling-a20f2755). This frees you from needing Webpack, Yarn, npm, or any other part of the JavaScript toolchain. All you need is the asset pipeline that's already included in Rails.
 
-With this approach you'll ship many small JavaScript files instead of one big JavaScript file. Thanks to HTTP/2 that no longer carries a material performance penalty during the initial transport, and in fact offers substantial benefits over the long run due to better caching dynamics. Whereas before any change to any JavaScript file included in your big bundle would invalidate the cache for the the whole bundle, now only the cache for that single file is invalidated.
+With this approach you'll ship many small JavaScript files instead of one big JavaScript file. Thanks to HTTP/2 that no longer carries a material performance penalty during the initial transport, and in fact offers substantial benefits over the long run due to better caching dynamics. Whereas before any change to any JavaScript file included in your big bundle would invalidate the cache for the whole bundle, now only the cache for that single file is invalidated.
 
-There's [native support for import maps in Chrome/Edge 89+](https://caniuse.com/?search=importmap), and [a shim available](https://github.com/guybedford/es-module-shims) for any browser with basic ESM support. So your app will be able to work with all the evergreen browsers.
+[Import maps are supported natively in all major, modern browsers](https://caniuse.com/?search=importmap). If you need to work with legacy browsers without native support, you can explore using [the shim available](https://github.com/guybedford/es-module-shims).
 
 
 ## Installation
 
-Importmap for Rails is automatically included in Rails 7+ for new applications, but you can also install it manually in existing applications: 
+Importmap for Rails is automatically included in Rails 7+ for new applications, but you can also install it manually in existing applications:
 
-1. Add `importmap-rails` to your Gemfile with `gem 'importmap-rails'`
-2. Run `./bin/bundle install`
-3. Run `./bin/rails importmap:install`
+1. Run `./bin/bundle add importmap-rails`
+2. Run `./bin/rails importmap:install`
 
 Note: In order to use JavaScript from Rails frameworks like Action Cable, Action Text, and Active Storage, you must be running Rails 7.0+. This was the first version that shipped with ESM compatible builds of these libraries.
 
+You can pin those libraries manually by relying on the compiled versions included in Rails like this:
+
+```ruby
+pin "@rails/actioncable", to: "actioncable.esm.js"
+pin "@rails/activestorage", to: "activestorage.esm.js"
+pin "@rails/actiontext", to: "actiontext.esm.js"
+pin "trix"
+```
+
+## How do importmaps work?
+
+At their core, importmaps are essentially a string substitution for what are referred to as "bare module specifiers". A "bare module specifier" looks like this: `import React from "react"`. This is not compatible with the ES Module loader spec. Instead, to be ESM compatible, you must provide 1 of the 3 following types of specifiers:
+
+- Absolute path:
+```js
+import React from "/Users/DHH/projects/basecamp/node_modules/react"
+```
+
+- Relative path:
+```js
+import React from "./node_modules/react"
+```
+
+- HTTP path:
+```js
+import React from "https://ga.jspm.io/npm:react@17.0.1/index.js"
+```
+
+Importmap-rails provides a clean API for mapping "bare module specifiers" like `"react"`
+to 1 of the 3 viable ways of loading ES Module javascript packages.
+
+For example:
+
+```rb
+# config/importmap.rb
+pin "react", to: "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```
+
+means "every time you see `import React from "react"`
+change it to `import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"`"
+
+```js
+import React from "react"
+// => import React from "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```
 
 ## Usage
 
 The import map is setup through `Rails.application.importmap` via the configuration in `config/importmap.rb`. This file is automatically reloaded in development upon changes, but note that you must restart the server if you remove pins and need them gone from the rendered importmap or list of preloads.
 
-This import map is inlined in the `<head>` of your application layout using `<%= javascript_importmap_tags %>`, which will setup the JSON configuration inside a `<script type="importmap">` tag. After that, the [es-module-shim](https://github.com/guybedford/es-module-shims) is loaded, and then finally the application entrypoint is imported via `<script type="module">import "application"</script>`. That logical entrypoint, `application`, is mapped in the importmap script tag to the file `app/javascript/application.js`.
+This import map is inlined in the `<head>` of your application layout using `<%= javascript_importmap_tags %>`, which will setup the JSON configuration inside a `<script type="importmap">` tag. Then the application entrypoint is imported via `<script type="module">import "application"</script>`. That logical entrypoint, `application`, is mapped in the importmap script tag to the file `app/javascript/application.js`.
 
 It's in `app/javascript/application.js` you setup your application by importing any of the modules that have been defined in the import map. You can use the full ESM functionality of importing any particular export of the modules or everything.
 
 It makes sense to use logical names that match the package names used by npm, such that if you later want to start transpiling or bundling your code, you won't have to change any module imports.
 
+### Local modules
 
-## Using npm packages via JavaScript CDNs
+If you want to import local js module files from `app/javascript/src` or other sub-folders of `app/javascript` (such as `channels`), you must pin these to be able to import them. You can use `pin_all_from` to pick all files in a specific folder, so you don't have to `pin` each module individually.
 
-Importmap for Rails is designed to be used with JavaScript CDNs for your npm package dependencies. The CDNs provide pre-compiled distribution versions ready to use, and offer a fast, efficient way of serving them.
+```rb
+# config/importmap.rb
+pin_all_from 'app/javascript/src', under: 'src', to: 'src'
 
-You can use the `./bin/importmap` command that's added as part of the install to pin, unpin, or update npm packages in your import map. This command uses an API from [JSPM.org](https://jspm.org) to resolve your package dependencies efficiently, and then add the pins to your `config/importmap.rb` file. It can resolve these dependencies from JSPM itself, but also from other CDNs, like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com).
+# With automatic integrity calculation for enhanced security
+enable_integrity!
+pin_all_from 'app/javascript/controllers', under: 'controllers', integrity: true
+```
 
-It works like so:
+The `:to` parameter is only required if you want to change the destination logical import name. If you drop the :to option, you must place the :under option directly after the first parameter.
 
-```bash
-./bin/importmap pin react react-dom
-Pinning "react" to https://ga.jspm.io/npm:react@17.0.2/index.js
-Pinning "react-dom" to https://ga.jspm.io/npm:react-dom@17.0.2/index.js
-Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
-Pinning "scheduler" to https://ga.jspm.io/npm:scheduler@0.20.2/index.js
+The `enable_integrity!` call enables integrity calculation globally, and `integrity: true` automatically calculates integrity hashes for all files in the directory, providing security benefits without manual hash management.
 
-./bin/importmap json
+Allows you to:
 
-{
-  "imports": {
-    "application": "/assets/application-37f365cbecf1fa2810a8303f4b6571676fa1f9c56c248528bc14ddb857531b95.js",
-    "react": "https://ga.jspm.io/npm:react@17.0.2/index.js",
-    "react-dom": "https://ga.jspm.io/npm:react-dom@17.0.2/index.js",
-    "object-assign": "https://ga.jspm.io/npm:object-assign@4.1.1/index.js",
-    "scheduler": "https://ga.jspm.io/npm:scheduler@0.20.2/index.js"
-  }
-}
+```js
+// app/javascript/application.js
+import { ExampleFunction } from 'src/example_function'
 ```
+Which imports the function from `app/javascript/src/example_function.js`.
 
-As you can see, the two packages react and react-dom resolve to a total of four dependencies, when resolved via the jspm default.
+Note: Sprockets used to serve assets (albeit without filename digests) it couldn't find from the `app/javascripts` folder with logical relative paths, meaning pinning local files wasn't needed. Propshaft doesn't have this fallback, so when you use Propshaft you have to pin your local modules.
 
-Now you can use these in your application.js entrypoint like you would any other module:
+## Using npm packages via JavaScript CDNs
 
-```js
-import React from "react"
-import ReactDOM from "react-dom"
-```
+Importmap for Rails downloads and vendors your npm package dependencies via JavaScript CDNs that provide pre-compiled distribution versions.
 
-You can also designate a specific version to pin:
+You can use the `./bin/importmap` command that's added as part of the install to pin, unpin, or update npm packages in your import map. By default this command uses an API from [JSPM.org](https://jspm.org) to resolve your package dependencies efficiently, and then add the pins to your `config/importmap.rb` file.
 
 ```bash
-./bin/importmap pin react@17.0.1
-Pinning "react" to https://ga.jspm.io/npm:react@17.0.1/index.js
-Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+./bin/importmap pin react
+Pinning "react" to vendor/javascript/react.js via download from https://ga.jspm.io/npm:react@19.1.0/index.js
 ```
 
-Or even remove pins:
+This will produce a pin in your `config/importmap.rb` like so:
 
-```bash
-./bin/importmap unpin react
-Unpinning "react"
-Unpinning "object-assign"
+```ruby
+pin "react" # @19.1.0
 ```
 
-If you pin a package that has already been pinned, it'll be updated inline, along with its dependencies.
+Other CDNs like [unpkg.com](https://unpkg.com) and [jsdelivr.com](https://www.jsdelivr.com) can be specified with `--from`:
 
-You can control the environment of the package for packages with separate "production" (the default) and "development" builds:
+```bash
+./bin/importmap pin react --from unpkg
+Pinning "react" to vendor/javascript/react.js via download from https://unpkg.com/react@19.1.0/index.js
+```
 
 ```bash
-./bin/importmap pin react --env development
-Pinning "react" to https://ga.jspm.io/npm:react@17.0.2/dev.index.js
-Pinning "object-assign" to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+./bin/importmap pin react --from jsdelivr
+Pinning "react" to vendor/javascript/react.js via download from https://cdn.jsdelivr.net/npm/react@19.1.0/index.js
 ```
 
-You can also pick an alternative, supported CDN provider when pinning, like `unpkg` or `jsdelivr` (`jspm` is the default):
+The packages are downloaded to `vendor/javascript`, which you can check into your source control, and they'll be available through your application's own asset pipeline serving.
+
+If you later wish to remove a downloaded pin:
 
 ```bash
-./bin/importmap pin react --from jsdelivr
-Pinning "react" to https://cdn.jsdelivr.net/npm/react@17.0.2/index.js
+./bin/importmap unpin react
+Unpinning and removing "react"
 ```
 
-Remember, though, that if you switch a pin from one provider to another, you may have to clean up dependencies added by the first provider that isn't used by the second provider.
+## Subresource Integrity (SRI)
 
-Run `./bin/importmap` to see all options.
+For enhanced security, importmap-rails supports [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes for packages loaded from external CDNs.
 
-Note that this command is merely a convenience wrapper to resolving logical package names to CDN URLs. You can also just lookup the CDN URLs yourself, and then pin those. For example, if you wanted to use Skypack for React, you could just add the following to `config/importmap.rb`:
+### Automatic integrity for local assets
+
+To enable automatic integrity calculation for local assets served by the Rails asset pipeline, you must first call `enable_integrity!` in your importmap configuration:
 
 ```ruby
-pin "react", to: "https://cdn.skypack.dev/react"
+# config/importmap.rb
+
+# Enable integrity calculation globally
+enable_integrity!
+
+# With integrity enabled, these will auto-calculate integrity hashes
+pin "application"                                               # Auto-calculated integrity
+pin "admin", to: "admin.js"                                     # Auto-calculated integrity
+pin_all_from "app/javascript/controllers", under: "controllers" # Auto-calculated integrity
+
+# Mixed usage - explicitly controlling integrity
+pin "cdn_package", integrity: "sha384-abc123..." # Pre-calculated hash
+pin "no_integrity_package", integrity: false     # Explicitly disable integrity
+pin "nil_integrity_package", integrity: nil      # Explicitly disable integrity
 ```
 
+This is particularly useful for:
+* **Local JavaScript files** managed by your Rails asset pipeline
+* **Bulk operations** with `pin_all_from` where calculating hashes manually would be tedious
+* **Development workflow** where asset contents change frequently
 
-## Downloading vendor files from the JavaScript CDN
+**Note:** Integrity calculation is opt-in and must be enabled with `enable_integrity!`. This behavior can be further controlled by setting `integrity: false` or `integrity: nil` on individual pins.
 
-If you don't want to use a JavaScript CDN in production, you can also download vendored files from the CDN when you're setting up your pins:
+**Important for Propshaft users:** SRI support requires Propshaft 1.2+ and you must configure the integrity hash algorithm in your application:
 
-```bash
-./bin/importmap pin react --download
-Pinning "react" to vendor/react.js via download from https://ga.jspm.io/npm:react@17.0.2/index.js
-Pinning "object-assign" to vendor/object-assign.js via download from https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+```ruby
+# config/application.rb or config/environments/*.rb
+config.assets.integrity_hash_algorithm = 'sha256'  # or 'sha384', 'sha512'
 ```
 
-This will produce pins in your `config/importmap.rb` like so:
+Without this configuration, integrity will be disabled by default when using Propshaft. Sprockets includes integrity support out of the box.
 
-```ruby
-pin "react", to: "vendor/react.js" # https://ga.jspm.io/npm:react@17.0.2/index.js
-pin "object-assign", to: "vendor/object-assign.js" # https://ga.jspm.io/npm:object-assign@4.1.1/index.js
+**Example output with `enable_integrity!` and `integrity: true`:**
+```json
+{
+  "imports": {
+    "application": "/assets/application-abc123.js",
+    "controllers/hello_controller": "/assets/controllers/hello_controller-def456.js"
+  },
+  "integrity": {
+    "/assets/application-abc123.js": "sha256-xyz789...",
+    "/assets/controllers/hello_controller-def456.js": "sha256-uvw012..."
+  }
+}
 ```
 
-The packages are downloaded to `app/javascript/vendor`, which you can check into your source control, and they'll be available through your application's own asset pipeline serving.
+### How integrity works
 
-If you later wish to remove a downloaded pin, you again pass `--download`:
+The integrity hashes are automatically included in your import map and module preload tags:
 
-```bash
-./bin/importmap unpin react --download
-Unpinning and removing "react"
-Unpinning and removing "object-assign"
+**Import map JSON:**
+```json
+{
+  "imports": {
+    "lodash": "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js",
+    "application": "/assets/application-abc123.js",
+    "controllers/hello_controller": "/assets/controllers/hello_controller-def456.js"
+  },
+  "integrity": {
+    "https://ga.jspm.io/npm:lodash@4.17.21/lodash.js": "sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF"
+    "/assets/application-abc123.js": "sha256-xyz789...",
+    "/assets/controllers/hello_controller-def456.js": "sha256-uvw012..."
+  }
+}
 ```
 
-Just like with a normal pin, you can also update a pin by running the `pin --download` command again.
+**Module preload tags:**
+```html
+<link rel="modulepreload" href="https://ga.jspm.io/npm:lodash@4.17.21/lodash.js" integrity="sha384-PkIkha4kVPRlGtFantHjuv+Y9mRefUHpLFQbgOYUjzy247kvi16kLR7wWnsAmqZF">
+<link rel="modulepreload" href="/assets/application-abc123.js" integrity="sha256-xyz789...">
+<link rel="modulepreload" href="/assets/controllers/hello_controller-def456.js" integrity="sha256-uvw012...">
+```
 
+Modern browsers will automatically validate these integrity hashes when loading the JavaScript modules, ensuring the files haven't been modified.
 
 ## Preloading pinned modules
 
-To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, importmap-rails supports [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload). Pinned modules can be preloaded by appending `preload: true` to the pin.
+To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, importmap-rails uses [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload) by default. If you don't want to preload a dependency, because you want to load it on-demand for efficiency, append `preload: false` to the pin.
 
 Example:
 
 ```ruby
 # config/importmap.rb
-pin "@github/hotkey", to: "https://ga.jspm.io/npm:@github/hotkey@1.4.4/dist/index.js", preload: true
-pin "md5", to: "https://cdn.jsdelivr.net/npm/md5@2.3.0/md5.js"
+pin "@github/hotkey", to: "@github--hotkey.js" # file lives in vendor/javascript/@github--hotkey.js
+pin "md5", preload: false # file lives in vendor/javascript/md5.js
 
 # app/views/layouts/application.html.erb
-<%= javascript_importmap_tags %> 
+<%= javascript_importmap_tags %>
 
 # will include the following link before the importmap is setup:
-<link rel="modulepreload" href="https://ga.jspm.io/npm:@github/hotkey@1.4.4/dist/index.js">
+<link rel="modulepreload" href="/assets/javascript/@github--hotkey.js">
 ...
 ```
 
+You can also specify which entry points to preload a particular dependency in by providing `preload:` a string or array of strings.
+
+Example:
+
+```ruby
+# config/importmap.rb
+pin "@github/hotkey", to: "@github--hotkey.js", preload: 'application'
+pin "md5", preload: ['application', 'alternate']
+
+# app/views/layouts/application.html.erb
+<%= javascript_importmap_tags 'alternate' %>
+
+# will include the following link before the importmap is setup:
+<link rel="modulepreload" href="/assets/javascript/md5.js">
+...
+```
+
+
+
 ## Composing import maps
 
 By default, Rails loads import map definition from the application's `config/importmap.rb` to the `Importmap::Map` object available at `Rails.application.importmap`.
 
-You can combine multiple import maps by drawing their definitions onto the `Rails.application.importmap`. For example, appending import maps defined in Rails engines:
+You can combine multiple import maps by adding paths to additional import map configs to `Rails.application.config.importmap.paths`. For example, appending import maps defined in Rails engines:
 
 ```ruby
 # my_engine/lib/my_engine/engine.rb
@@ -171,8 +271,9 @@ You can combine multiple import maps by drawing their definitions onto the `Rail
 module MyEngine
   class Engine < ::Rails::Engine
     # ...
-    initializer "my-engine.importmap", after: "importmap" do |app|
-      app.importmap.draw(Engine.root.join("config/importmap.rb"))
+    initializer "my-engine.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+      # ...
     end
   end
 end
@@ -187,41 +288,88 @@ pin_all_from File.expand_path("../app/assets/javascripts", __dir__)
 ```
 
 
+## Selectively importing modules
+
+You can selectively import your javascript modules on specific pages.
+
+Create your javascript in `app/javascript`:
+
+```js
+// /app/javascript/checkout.js
+// some checkout specific js
+```
+
+Pin your js file:
+
+```rb
+# config/importmap.rb
+# ... other pins...
+pin "checkout", preload: false
+```
+
+Import your module on the specific page. Note: you'll likely want to use a `content_for` block on the specific page/partial, then yield it in your layout.
+
+```erb
+<% content_for :head do %>
+  <%= javascript_import_module_tag "checkout" %>
+<% end %>
+```
+
+**Important**: The `javascript_import_module_tag` should come after your `javascript_importmap_tags`
+
+```erb
+<%= javascript_importmap_tags %>
+<%= yield(:head) %>
+```
+
+
 ## Include a digest of the import map in your ETag
 
-If you're using [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) generated by Rails helpers like `stale?` or `fresh_when`, you need to include the digest of the import map into this calculation. Otherwise your application will return 302 cache responses even when your JavaScript assets have changed. You can avoid this with something like:
+If you're using [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) generated by Rails helpers like `stale?` or `fresh_when`, you need to include the digest of the import map into this calculation. Otherwise your application will return [304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304) cache responses even when your JavaScript assets have changed. You can avoid this using the `stale_when_importmap_changes` method:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  etag { Rails.application.importmap.digest(resolver: helpers) if request.format&.html? }
+  stale_when_importmap_changes
 end
 ```
 
+This will add the digest of the importmap to the etag calculation when the request format is HTML.
+
 
 ## Sweeping the cache in development and test
 
 Generating the import map json and modulepreloads may require resolving hundreds of assets. This can take a while, so these operations are cached, but in development and test, we watch for changes to both `config/importmap.rb` and files in `app/javascript` to clear this cache. This feature can be controlled in an environment configuration file via the boolean `config.importmap.sweep_cache`.
 
-If you're pinning local files from outside of `app/javascript`, you'll need to add them to the cache sweeper configuration or restart your development server upon changes to those external files. To add them to the configuration to clear the cache on changes, for instance when locally developing an engine, use an initializer like the following sample `config/initializers/importmap-caching.rb`:
+If you're pinning local files from outside of `app/javascript`, you'll need to add them to the cache sweeper configuration or restart your development server upon changes to those external files. For example, here's how you can do it for Rails engine:
 
 ```ruby
-if Rails.env.development?
-  Rails.application.importmap.cache_sweeper watches: [
-    Rails.application.root.join("app/javascript"),
-    MyEngine::Engine.root.join("app/assets/javascripts"),
-  ]
+# my_engine/lib/my_engine/engine.rb
+
+module MyEngine
+  class Engine < ::Rails::Engine
+    # ...
+    initializer "my-engine.importmap", before: "importmap" do |app|
+      # ...
+      app.config.importmap.cache_sweepers << Engine.root.join("app/assets/javascripts")
+    end
+  end
 end
 ```
 
-## Expected errors from using the es-module-shim
+## Checking for outdated or vulnerable packages
 
-While import maps are native in Chrome and Edge, they need a shim in other browsers that'll produce a JavaScript console error like `TypeError: Module specifier, 'application' does not start with "/", "./", or "../".`. This error is normal and does not have any user-facing consequences.
+Importmap for Rails provides two commands to check your pinned packages:
+- `./bin/importmap outdated` checks the NPM registry for new versions
+- `./bin/importmap audit` checks the NPM registry for known security issues
 
-In Firefox. when opening the browser console, the asm.js module lexer build will run in unoptimized mode due to the debugger attaching. This gives a warning message `"asm.js type error: Disabled because no suitable wasm compiler is available"` which is as expected. When the console is closed again, the asm.js optimizations are fully applied, and this can even be verified with the console open by disabling the debugger in `about:config` and reloading the page.
+## Supporting legacy browsers such as Safari on iOS 15
 
-## Turning off the shim
+If you want to support [legacy browsers that do not support import maps](https://caniuse.com/import-maps) such as [iOS 15.8.1 released on 22 Jan 2024](https://support.apple.com/en-us/HT201222), insert [`es-module-shims`](https://github.com/guybedford/es-module-shims) before `javascript_importmap_tags` as below.
 
-Under certain circumstances, like running system tests using chromedriver under CI (which may be resource constrained and trigger errors in certain cases), you may want to explicitly turn off including the shim. You can do this by calling the bulk tag helper with `javascript_importmap_tags("application", shim: false)`. Thus you can pass in something like `shim: !ENV["CI"]`. If you want, and are sure you're not doing any full-page caching, you can also connect this directive to a user agent check (using a gem like `useragent`) to check whether the browser is chrome/edge 89+. But you really shouldn't have to, as the shim is designed to gracefully work with natively compatible drivers.
+```erb
+<script async src="https://ga.jspm.io/npm:es-module-shims@1.8.2/dist/es-module-shims.js" data-turbo-track="reload"></script>
+<%= javascript_importmap_tags %>
+```
 
 ## License
 

data/Rakefile

@@ -3,8 +3,6 @@ require "bundler/setup"
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
-load "rails/tasks/statistics.rake"
-
 require "bundler/gem_tasks"
 
 require "rake/testtask"

data/app/controllers/importmap/freshness.rb

@@ -0,0 +1,5 @@
+module Importmap::Freshness
+  def stale_when_importmap_changes
+    etag { Rails.application.importmap.digest(resolver: helpers) if request.format&.html? }
+  end
+end

data/app/helpers/importmap/importmap_tags_helper.rb

@@ -1,54 +1,47 @@
 module Importmap::ImportmapTagsHelper
   # Setup all script tags needed to use an importmap-powered entrypoint (which defaults to application.js)
-  def javascript_importmap_tags(entry_point = "application", shim: true)
+  def javascript_importmap_tags(entry_point = "application", importmap: Rails.application.importmap)
     safe_join [
-      javascript_inline_importmap_tag,
-      javascript_importmap_module_preload_tags,
-      (javascript_importmap_shim_nonce_configuration_tag if shim),
-      (javascript_importmap_shim_tag if shim),
+      javascript_inline_importmap_tag(importmap.to_json(resolver: self)),
+      javascript_importmap_module_preload_tags(importmap, entry_point:),
       javascript_import_module_tag(entry_point)
-    ].compact, "\n"
+    ], "\n"
   end
 
   # Generate an inline importmap tag using the passed `importmap_json` JSON string.
   # By default, `Rails.application.importmap.to_json(resolver: self)` is used.
   def javascript_inline_importmap_tag(importmap_json = Rails.application.importmap.to_json(resolver: self))
     tag.script importmap_json.html_safe,
-      type: "importmap", "data-turbo-track": "reload", nonce: content_security_policy_nonce
-  end
-
-  # Configure es-modules-shim with nonce support if the application is using a content security policy.
-  def javascript_importmap_shim_nonce_configuration_tag
-    if content_security_policy?
-      tag.script({ nonce: content_security_policy_nonce }.to_json.html_safe, 
-        type: "esms-options", nonce: content_security_policy_nonce)
-    end
-  end
-
-  # Include the es-modules-shim needed to make importmaps work in browsers without native support (like Firefox + Safari).
-  def javascript_importmap_shim_tag(minimized: true)
-    javascript_include_tag minimized ? "es-module-shims.min.js" : "es-module-shims.js",
-      async: true, "data-turbo-track": "reload", nonce: content_security_policy_nonce
+      type: "importmap", "data-turbo-track": "reload", nonce: request&.content_security_policy_nonce
   end
 
   # Import a named JavaScript module(s) using a script-module tag.
   def javascript_import_module_tag(*module_names)
     imports = Array(module_names).collect { |m| %(import "#{m}") }.join("\n")
-    tag.script imports.html_safe, 
-      type: "module", nonce: content_security_policy_nonce
+    tag.script imports.html_safe, type: "module", nonce: request&.content_security_policy_nonce
   end
 
   # Link tags for preloading all modules marked as preload: true in the `importmap`
   # (defaults to Rails.application.importmap), such that they'll be fetched
   # in advance by browsers supporting this link type (https://caniuse.com/?search=modulepreload).
-  def javascript_importmap_module_preload_tags(importmap = Rails.application.importmap)
-    javascript_module_preload_tag(*importmap.preloaded_module_paths(resolver: self))
+  def javascript_importmap_module_preload_tags(importmap = Rails.application.importmap, entry_point: "application")
+    packages = importmap.preloaded_module_packages(resolver: self, entry_point:, cache_key: entry_point)
+
+    _generate_preload_tags(packages) { |path, package| [path, { integrity: package.integrity }] }
   end
 
   # Link tag(s) for preloading the JavaScript module residing in `*paths`. Will return one link tag per path element.
   def javascript_module_preload_tag(*paths)
-    safe_join(Array(paths).collect { |path|
-      tag.link rel: "modulepreload", href: path, nonce: content_security_policy_nonce
-    }, "\n")
+    _generate_preload_tags(paths) { |path| [path, {}] }
   end
+
+  private
+    def _generate_preload_tags(items)
+      content_security_policy_nonce = request&.content_security_policy_nonce
+
+      safe_join(Array(items).collect { |item|
+        path, options = yield(item)
+        tag.link rel: "modulepreload", href: path, nonce: content_security_policy_nonce, **options
+      }, "\n")
+    end
 end