README.md in importmap-rails-0.8.1 vs README.md in importmap-rails-0.8.2
- old
+ new
@@ -15,11 +15,47 @@
2. Run `./bin/bundle install`
3. 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.
+## 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/importmaps.rb
+pin "react" to "https://ga.jspm.io/npm:react@17.0.2/index.js"
+```
+
+means "everytime 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`.
@@ -121,14 +157,14 @@
```
This will produce pins in your `config/importmap.rb` like so:
```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
+pin "react" # https://ga.jspm.io/npm:react@17.0.2/index.js
+pin "object-assign" # https://ga.jspm.io/npm:object-assign@4.1.1/index.js
```
-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.
+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, you again pass `--download`:
```bash
./bin/importmap unpin react --download