importmap-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e3127a8154739158fd8b7feea069b5ae6e8d353d36ba16fa446095f26b70ae0
-  data.tar.gz: c6d7e65df38a98e5c31b5195ee298651c6550cb97e3c438ebf46c8a5290a17b6
+  metadata.gz: 97b5ca5be348b06c3b3b04b5aaccc99fa5bc55a8a65c664d25e37cf6f8be2586
+  data.tar.gz: 3c377792bec10f97d819640e801dc9a36112ef009da0902eba36a2d873d67623
 SHA512:
-  metadata.gz: 2e186a8e9785fc7da247ddf1c459d005977a8ce21fb2403aa3e3b63c2b938b9ffa682df1742292633dd9afcae0f7a7f68582af2cafc642afd04195564fd5c2a1
-  data.tar.gz: fc85e86b9d747e9e84e8e009bcca8e4746f6477f25d6355b705958fb917818872005127c5ad9ac8e9f9f7594d1ac06b68013038ab351cd072d45c0d4dc76b7ce
+  metadata.gz: 66c0ee6695329e2cba7e6bdf545d4415fa3bc92218fff791ec21977f53fe8294c536cf5fefba0d00c7ceb5859529e32c2cadbbad0097c21bd82efba84402a0f7
+  data.tar.gz: 95be4c078375c1e11f7061dedc195c9bbec3f57e870104ef429e64586100f8872ba4ab94398b4b7e6003e07a77514d7a74682428b8e1b85d889bf028c43a8683

data/README.md

@@ -1,49 +1,48 @@
 # 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. Without the need for such preprocessing, you can build advanced Rails applications without 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 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 HTTP2 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 HTTP2 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.
 
 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.
 
 
 ## Installation
 
-1. Add `importmap-rails` to your Gemfile with `gem 'importmap-rails'` (make sure it's included before any gems using it!)
+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`
 
-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/importmap.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` assignment, which by default is setup in `config/importmap.rb` after running the installer. 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.
+The import map is setup through `Rails.application.config.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 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/javascript/application.js`, which is copied and digested by the asset pipeline.
+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`.
 
 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'll not have to change any module imports.
+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.
 
 
 ## Using node modules via JavaScript CDNs
 
 Importmap for Rails is designed to be used with JavaScript CDNs for your node package dependencies. The CDNs provide pre-compiled distribution versions ready to use, and offer a fast, efficient way of serving them.
 
-You can use the bin/importmap command that's added as part of the install to pin additional packages to your importmap. This command uses an API from JSPM.org to resolve your package dependencies most 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, jsdelivr.com, skypack.dev, etc.
+You can use the `./bin/importmap` command that's added as part of the install to pin, unpin, or update node 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).
 
 It works like so:
 
 ```bash
-./bin/importmap pin react react-dom
-
-Pinned 'react' to https://ga.jspm.io/npm:react@17.0.2/index.js
-Pinned 'react-dom' to https://ga.jspm.io/npm:react-dom@17.0.2/index.js
-Pinned 'object-assign' to https://ga.jspm.io/npm:object-assign@4.1.1/index.js
-Pinned 'scheduler' to https://ga.jspm.io/npm:scheduler@0.20.2/index.js
+/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
 
 ./bin/importmap json
 
@@ -67,10 +66,65 @@ import React from "react"
 import ReactDOM from "react-dom"
 ```
 
+You can also designate a specific version to pin:
+
+```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
+```
+
+Or even remove pins:
+
+```bash
+./bin/importmap unpin react
+Unpinning "react"
+Unpinning "object-assign"
+```
+
+If you pin a package that has already been pinned, it'll be updated inline, along with its dependencies.
+
+You can control the environment of the package for packages with separate "production" (the default) and "development" builds:
+
+```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
+```
+
+You can also pick an alternative, supported CDN provider when pinning, like `unpkg` or `jsdelivr` (`jspm` is the default):
+
+```bash
+./bin/importmap pin react --from jsdelivr
+Pinning "react" to https://cdn.jsdelivr.net/npm/react@17.0.2/index.js
+```
+
+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.
+
+Run `./bin/importmap` to see all options.
+
+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`:
+
+```ruby
+pin "react", to: "https://cdn.skypack.dev/react"
+```
+
+
+## What if I don't like to use a JavaScript CDN?
+
+You always have the option to simply download the compiled JavaScript packages from the CDNs, and saving them locally in your application. You can put such files in app/javascript/vendor, and then reference them with local pins, like:
+
+```ruby
+# config/importmap.rb
+pin "react", to: "vendor/react@17.0.2.js"
+```
+
+But using a JavaScript CDN is fast, secure, and easier to deal with. Start there.
+
 
 ## Preloading pinned modules
 
-To mitigate the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, we use [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload). Pinned modules are preloaded by default, but you can turn this off with `preload: false`.
+To avoid the waterfall effect where the browser has to load one file after another before it can get to the deepest nested import, we use [modulepreload links](https://developers.google.com/web/updates/2017/12/modulepreload). Pinned modules are preloaded by default, but you can turn this off with `preload: false`.
 
 Example:
 

data/app/helpers/importmap/importmap_tags_helper.rb

@@ -29,7 +29,7 @@ module Importmap::ImportmapTagsHelper
   # (defaults to Rails.application.config.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.config.importmap)
-    javascript_module_preload_tag *importmap.preloaded_module_paths(resolver: self)
+    javascript_module_preload_tag(*importmap.preloaded_module_paths(resolver: self))
   end
 
   # Link tag(s) for preloading the JavaScript module residing in `*paths`. Will return one link tag per path element.

data/lib/importmap/commands.rb

@@ -1,14 +1,40 @@
 require "thor"
-require "importmap/pinner"
+require "importmap/packager"
 
 class Importmap::Commands < Thor
+  include Thor::Actions
+  
   desc "pin [*PACKAGES]", "Pin new packages"
   option :env, type: :string, aliases: :e, default: "production"
   option :from, type: :string, aliases: :f, default: "jspm"
   def pin(*packages)
-    if imports = Importmap::Pinner.new.pin(*packages, env: options[:env], from: options[:from])
+    if imports = packager.import(*packages, env: options[:env], from: options[:from])
       imports.each do |package, url|
-        puts "Pinned '#{package}' to #{url}"
+        puts %(Pinning "#{package}" to #{url})
+
+        pin = packager.pin_for(package, url)
+
+        if packager.packaged?(package)
+          gsub_file("config/importmap.rb", /^pin "#{package}".*$/, pin, verbose: false)
+        else
+          append_to_file("config/importmap.rb", "#{pin}\n", verbose: false)
+        end
+      end
+    else
+      puts "Couldn't find any packages in #{packages.inspect} on #{options[:provider]}"
+    end
+  end
+
+  desc "unpin [*PACKAGES]", "Unpin existing packages"
+  option :env, type: :string, aliases: :e, default: "production"
+  option :from, type: :string, aliases: :f, default: "jspm"
+  def unpin(*packages)
+    if imports = packager.import(*packages, env: options[:env], from: options[:from])
+      imports.each do |package, url|
+        if packager.packaged?(package)
+          puts %(Unpinning "#{package}")
+          remove_line_from_file "config/importmap.rb", /pin "#{package}"/
+        end
       end
     else
       puts "Couldn't find any packages in #{packages.inspect} on #{options[:provider]}"
@@ -19,6 +45,22 @@ class Importmap::Commands < Thor
   def json
     puts Rails.application.config.importmap.to_json(resolver: ActionController::Base.helpers)
   end
+
+  private
+    def packager
+      @packager ||= Importmap::Packager.new
+    end
+
+    def remove_line_from_file(path, pattern)
+      path = File.expand_path(path, destination_root)
+
+      all_lines = File.readlines(path)
+      with_lines_removed = all_lines.select { |line| line !~ pattern }
+
+      File.open(path, "w") do |file|
+        with_lines_removed.each { |line| file.write(line) }
+      end
+    end
 end
 
 Importmap::Commands.start(ARGV)

data/lib/importmap/map.rb

@@ -9,14 +9,14 @@ class Importmap::Map
   end
 
   def draw(path = nil, &block)
-    if path
+    if path && File.exist?(path)
       begin
         instance_eval(File.read(path))
       rescue Exception => e
         Rails.logger.error "Unable to parse import map from #{path}: #{e.message}"
         raise "Unable to parse import map from #{path}: #{e.message}"
       end
-    else
+    elsif block_given?
       instance_eval(&block)
     end
 

data/lib/importmap/packager.rb

@@ -0,0 +1,39 @@
+require "httparty"
+require "minitest/mock"
+
+class Importmap::Packager
+  include HTTParty
+  base_uri "https://api.jspm.io"
+
+  def initialize(importmap_path = "config/importmap.rb")
+    @importmap_path = importmap_path
+  end
+
+  def import(*packages, env: "production", from: "jspm")
+    response = self.class.post("/generate", body: {
+      "install"      => Array(packages), 
+      "flattenScope" => true,
+      "env"          => [ "browser", "module", env ],
+      "provider"     => from.to_s
+    }.to_json)
+    
+    case response.code
+    when 200 then response.dig("map", "imports")
+    when 404 then nil
+    else          response.send(:throw_exception)
+    end
+  end
+
+  def pin_for(package, url)
+    %(pin "#{package}", to: "#{url}")
+  end
+
+  def packaged?(package)
+    importmap.match(/^pin "#{package}".*$/)
+  end
+
+  private
+    def importmap
+      @importmap ||= File.read(@importmap_path)
+    end
+end

data/lib/importmap/version.rb

@@ -1,3 +1,3 @@
 module Importmap
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/install/config/importmap.rb

@@ -5,16 +5,6 @@
 # Use direct uploads for Active Storage (remember to import "@rails/activestorage" in your application.js)
 # pin "@rails/activestorage", to: "activestorage.esm.js"
 
-# Pin vendored modules by first adding the following to app/assets/config/manifest.js:
-# //= link_tree ../../../vendor/assets/javascripts .js
-# pin_all_from "vendor/assets/javascripts"
-
-# JavaScript CDN provider. Also available: :jsdelivr, :esmsh, :unpkg, :skypack
-provider :jspm
-
-# Use NPM libraries from CDN
-# pin "local-time", version: "2.1.0", file: "app/assets/javascripts/local-time.js"
-# pin "vue", version: "2.6.14", file: "dist/vue.esm.browser.js", from: :jsdelivr
-# pin "d3", version: "7.0.1", file: "?bundle", from: :esmsh
+# Use node modules from a JavaScript CDN by running ./bin/importmap
 
 pin "application"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: importmap-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-31 00:00:00.000000000 Z
+date: 2021-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -54,7 +54,7 @@ files:
 - lib/importmap/commands.rb
 - lib/importmap/engine.rb
 - lib/importmap/map.rb
-- lib/importmap/pinner.rb
+- lib/importmap/packager.rb
 - lib/importmap/reloader.rb
 - lib/importmap/version.rb
 - lib/install/bin/importmap

data/lib/importmap/pinner.rb

@@ -1,32 +0,0 @@
-require "httparty"
-
-class Importmap::Pinner
-  include HTTParty
-  base_uri "https://api.jspm.io"
-
-  def pin(*packages, env: "production", from: "jspm")
-    fetch_imports(*packages, env: env, provider: from)&.tap do |imports|
-      imports.each do |package, url|
-        append_to_importmap package, url
-      end
-    end
-  end
-
-  private
-    def append_to_importmap(package, url)
-      Rails.root.join("config/importmap.rb").open("a") do |config|
-        config.puts %(pin "#{package}", to: "#{url}")
-      end
-    end
-
-    def fetch_imports(*packages, env:, provider:)
-      response = self.class.post("/generate", body: {
-        "install"      => Array(packages), 
-        "flattenScope" => true,
-        "env"          => [ "browser", env ],
-        "provider"     => provider.to_s
-      }.to_json)
-      
-      response.dig("map", "imports")
-    end
-end