README.md in importmap-rails-0.1.2 vs README.md in importmap-rails-0.1.3
- old
+ new
@@ -13,11 +13,13 @@
2. Run `./bin/bundle install`
3. Run `./bin/rails importmap:install`
By default, all the files in `app/assets/javascripts` and the three major Rails JavaScript libraries are already mapped. You can add more mappings in `config/initializers/assets.rb`.
+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.
+
## Usage
The import map is configured programmatically through the `Rails.application.config.importmap.paths` assignment, which by default is setup in `config/initializers/assets.rb` after running the installer. (Note that since this is a config initializer, you must restart your development server after making any changes.)
This programmatically configured 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/assets/javascripts/application.js`, which is copied and digested by the asset pipeline.
@@ -33,9 +35,29 @@
```js
import "@hotwired/turbo-rails"
import "@hotwired/stimulus-autoloader"
```
+
+
+## Use with Skypack (and other CDNs)
+
+Instead of mapping JavaScript modules to files in your application's path, you can also reference them directly from JavaScript CDNs like Skypack. Simply add them to the `config/initializers/assets.rb` with the URL instead of the local path:
+
+```ruby
+Rails.application.config.importmap.paths.tap do |paths|
+ paths.asset "trix", path: "https://cdn.skypack.dev/trix"
+ paths.asset "md5", path: "https://cdn.skypack.dev/md5"
+end
+```
+
+Now you can use these in your application.js entrypoint like you would any other module:
+
+```js
+import "trix"
+import md5 from "md5"
+console.log(md5("Hash it out"))
+```
## 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.