importmap-rails 1.0.2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88dca9c2f87f4777a70f6d6e95bf7212c4f7392b04da6571f479c46b65805e28
-  data.tar.gz: c93c502ef9a4f739fe630bc24052ea4df3e17ce37ee5323a513ad5d302e0d7e1
+  metadata.gz: 33dce6ec9c0694844753828ea342c40c03dc7cc07460461b37e0310e995b9238
+  data.tar.gz: fa91a5de60f67973d7075e58c0f6ac45cf74bc023d96407072c65c616f546472
 SHA512:
-  metadata.gz: e058a2747e3a884535312eed0f21235d6ac98c5e7d8ba2c8cf702f52952b634cca93ec8c66f102168d60d696ab160d3ff9b08945f0419de627e58ae8a5f64633
-  data.tar.gz: bda6354071b0610aba6e1f7347b533d26a3a624b87038c19b0c8404ec347a37b7e1cffe41b36c4bedd4aa058f4981e359093982ea97b099cb8a1f9c57fd0657c
+  metadata.gz: 79168173967c286f3ffa36b912cd6a230159f225d1842a0d458b05a54ec8e53ac051cf7fd5903ffab43348b0bfcdf17f17cb1d065de31af6b4b392a5da33e039
+  data.tar.gz: d8eb7c52ace629023a350c01755f2f3a17a8b835905b019bb51599af9e058e2de213902acb1e3fa5b7d4d31f9a623f075b697b5270f5547de98c087a37096672

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

@@ -2,18 +2,17 @@
 
 [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.
+There's [native support for import maps in Chrome/Edge 89+/Firefox 108+](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.
 
 
 ## Installation
 
 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.
 
@@ -224,6 +223,41 @@ 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"
+```
+
+Import your module on the specific page. Note: you'll likely want to use a `content_for` block on the specifc 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:
@@ -257,13 +291,19 @@ end
 
 ## Expected errors from using the es-module-shim
 
-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.
+While import maps are native in Chrome, Edge, and Firefox, 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.
 
 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.
 
 ## Turning off the shim
 
-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.
+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+/firefox 108+. But you really shouldn't have to, as the shim is designed to gracefully work with natively compatible drivers.
+
+## Checking for outdated or vulnerable packages
+
+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
 
 ## License