importmap-rails 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5193a35b0581011cda86209dc8d5999fb9014b31f2bda311bbaffd1a2859dcff
-  data.tar.gz: 2ca482f5d6d97214b30308b869439ba2e5c3a61759ae6da20ae424ad1c88d3c3
+  metadata.gz: 0ec141d17e7859eac9dae9d91c47f04957f650f2cef7eeae7cc0449b9c92cd89
+  data.tar.gz: a2ce05f0a9c340668d407f5c7e2cf64b2fe68f262e567ab94fb1ccc029b10487
 SHA512:
-  metadata.gz: 5e8847248c55d406f8c2b49fa233711e1aa5c3d1de5119fba36f957f1723b1000740f2cf89010fef077e2693ed48e4b4234ba14e6b36330a67fa2291bec479a9
-  data.tar.gz: b523ecac3ecc3b0dd3a232b2b3917e6c116c4a2dc8e5954af2c6d79fae19d4d635af0d763ecdba0a0cc12797dae6f907e09d025fe84ff97cc858c6ff5f1ad00f
+  metadata.gz: e692f3214ec9f899ebffd3f239a8f87202811b8098de1f2b2906bcb2558d446801a34fe359b3a94b8b8768220d54918f089ed8149ede3e04708d29f435314872
+  data.tar.gz: 89eafbbd709cd3e9eb2e97310c96297465bb935b713e841c8b8f7c9dd4a7d4f59c05b0d5720f0d9087dfbcb3a7e86d17c6d89a6c061622c9b8e6387719707795

data/README.md

@@ -56,7 +56,34 @@ Now you can use these in your application.js entrypoint like you would any other
 import "trix"
 import md5 from "md5"
 console.log(md5("Hash it out"))
-``` 
+```
+
+
+## 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) in [browsers that support it](https://caniuse.com/?search=modulepreload). Pinned modules are preloaded by default, but you can turn this off with `preload: false`.
+
+Example:
+
+```ruby
+# config/initializers/importmap.rb
+Rails.application.config.importmap.draw do
+  pin "trix", to: "https://cdn.skypack.dev/trix"
+  pin "md5", to: "https://cdn.skypack.dev/md5", preload: false
+end
+
+# app/views/layouts/application.html.erb
+<%= javascript_importmap_tags %> 
+
+# will include the following link before the importmap is setup:
+<link rel="modulepreload" href="https://cdn.skypack.dev/trix">
+...
+```
+
+
+## Caching the import map and preload modules
+
+The import map should be cached in production, and is so by default via the `config.importmap.cached` option that will be set to the same value as `config.action_controller.perform_caching`, unless explicitly set differently.
 
 
 ## Expected errors from using the es-module-shim

data/app/assets/javascripts/es-module-shims@0.12.2.js

@@ -1,5 +1,8 @@
 /* ES Module Shims 0.12.2 */
 (function () {
+  // Temporary hack around https://github.com/guybedford/es-module-shims/issues/148
+  if (navigator.userAgent.match("Chrome")) return
+
   const resolvedPromise = Promise.resolve();
 
   let baseUrl;

data/app/helpers/importmap/importmap_tags_helper.rb

@@ -2,16 +2,17 @@ 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")
     safe_join [
+      javascript_importmap_module_preload_tags,
       javascript_inline_importmap_tag,
       javascript_importmap_shim_tag,
       javascript_import_module_tag(entry_point)
     ], "\n"
   end
 
-  # Generate an inline importmap tag using the passed `importmap` object to produce the JSON map.
-  # By default, `Rails.application.config.importmap` is used for this object.
-  def javascript_inline_importmap_tag(importmap = Rails.application.config.importmap)
-    tag.script(importmap.to_json(self).html_safe, type: "importmap", "data-turbo-track": "reload")
+  # Generate an inline importmap tag using the passed `importmap_json` JSON string.
+  # By default, `Rails.application.config.importmap.to_json(resolver: self)` is used.
+  def javascript_inline_importmap_tag(importmap_json = Rails.application.config.importmap.to_json(resolver: self))
+    tag.script(importmap_json.html_safe, type: "importmap", "data-turbo-track": "reload")
   end
 
   # Include the es-module-shim needed to make importmaps work in browsers without native support (like Firefox + Safari).
@@ -23,4 +24,16 @@ module Importmap::ImportmapTagsHelper
   def javascript_import_module_tag(module_name)
     tag.script %(import "#{module_name}").html_safe, type: "module"
   end
+
+  # Link tags for preloading all modules marked as preload: true in the `importmap`
+  # (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)
+  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 }, "\n")
+  end
 end

data/lib/importmap/engine.rb

@@ -9,6 +9,7 @@ module Importmap
     initializer "importmap.assets" do
       if Rails.application.config.respond_to?(:assets)
         Rails.application.config.assets.precompile += %w( es-module-shims.js )
+        Rails.application.config.assets.paths << Rails.root.join("app/javascript")
       end
     end
 
@@ -17,5 +18,11 @@ module Importmap
         helper Importmap::ImportmapTagsHelper
       end
     end
+
+    initializer "importmap.caching" do |app|
+      if Rails.application.config.importmap.cached.nil?
+        Rails.application.config.importmap.cached = app.config.action_controller.perform_caching
+      end
+    end
   end
 end

data/lib/importmap/map.rb

@@ -1,5 +1,6 @@
 class Importmap::Map
   attr_reader :files, :directories
+  attr_accessor :cached
 
   def initialize
     @files, @directories = {}, {}
@@ -9,51 +10,81 @@ class Importmap::Map
     instance_eval(&block)
   end
 
-  def pin(name, to:)
-    @files[name] = to
+  def pin(name, to: nil, preload: true)
+    @files[name] = MappedFile.new(name: name, path: to || "#{name}.js", preload: preload)
   end
 
-  def pin_all_from(path, append_base_path: false)
-    @directories[path] = append_base_path
+  def pin_all_from(path, under: nil, preload: true)
+    @directories[path] = MappedDir.new(path: path, under: under, preload: preload)
   end
 
-  def to_json(resolver)
-    { "imports" => resolve_asset_paths(resolver) }.to_json
+  def preloaded_module_paths(resolver:)
+    cache_as(:preloaded_module_paths) do
+      resolve_asset_paths(expanded_preloading_files_and_directories, resolver: resolver).values
+    end
+  end
+
+  def to_json(resolver:)
+    cache_as(:json) do
+      { "imports" => resolve_asset_paths(expanded_files_and_directories, resolver: resolver) }.to_json
+    end
   end
 
   private
-    def resolve_asset_paths(resolver)
-      expanded_files_and_directories.transform_values do |path|
+    MappedFile = Struct.new(:name, :path, :preload, keyword_init: true)
+    MappedDir  = Struct.new(:path, :under, :preload, keyword_init: true)
+
+    def cache_as(name)
+      if (cached && result = instance_variable_get("@cached_#{name}"))
+        result
+      else
+        instance_variable_set("@cached_#{name}", yield)
+      end
+    end
+
+    def resolve_asset_paths(paths, resolver:)
+      paths.transform_values do |mapping|
         begin
-          resolver.asset_path(path)
+          resolver.asset_path(mapping.path)
         rescue Sprockets::Rails::Helper::AssetNotFound
-          Rails.logger.warn "Importmap skipped missing path: #{path}"
+          Rails.logger.warn "Importmap skipped missing path: #{mapping.path}"
           nil
         end
       end.compact
     end
 
+    def expanded_preloading_files_and_directories
+      expanded_files_and_directories.select { |name, mapping| mapping.preload }
+    end
+
     def expanded_files_and_directories
       @files.dup.tap { |expanded| expand_directories_into expanded }
     end
 
     def expand_directories_into(paths)
-      @directories.each do |(path, append_base_path)|
-        if (absolute_path = absolute_root_of(path)).exist?
+      @directories.values.each do |mapping|
+        if (absolute_path = absolute_root_of(mapping.path)).exist?
           find_javascript_files_in_tree(absolute_path).each do |filename|
             module_filename = filename.relative_path_from(absolute_path)
-            module_name     = module_name_from(module_filename)
-            module_path     = append_base_path ? absolute_path.basename.join(module_filename).to_s : module_filename.to_s
+            module_name     = module_name_from(module_filename, mapping.under)
+            module_path     = mapping.under ? absolute_path.basename.join(module_filename).to_s : module_filename.to_s
 
-            paths[module_name] = module_path
+            paths[module_name] = MappedFile.new(name: module_name, path: module_path, preload: mapping.preload)
           end
         end
       end
     end
 
     # Strip off the extension, /index, or any versioning data for an absolute module name.
-    def module_name_from(filename)
-      filename.to_s.remove(filename.extname).remove("/index").split("@").first
+    def module_name_from(filename, under)
+      filename_without_ext = filename.to_s.remove(filename.extname)
+
+      if filename_without_ext == "index" && under
+        under
+      else
+        module_name = filename_without_ext.split("@").first
+        under ? "#{under}/#{module_name}" : module_name
+      end
     end
 
     def find_javascript_files_in_tree(path)

data/lib/importmap/version.rb

@@ -1,3 +1,3 @@
 module Importmap
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/lib/install/install.rb

@@ -9,7 +9,7 @@ else
 end
 
 say "Create application.js module as entrypoint"
-create_file Rails.root.join("app/assets/javascripts/application.js") do <<-JS
+create_file Rails.root.join("app/javascript/application.js") do <<-JS
 // Configure your import map in config/initializers/importmap.rb
 
 // import "@rails/actioncable"
@@ -18,25 +18,20 @@ JS
 end
 
 say "Ensure JavaScript files are in the asset pipeline manifest"
-append_to_file Rails.root.join("app/assets/config/manifest.js"), %(//= link_tree ../javascripts .js\n)
+append_to_file Rails.root.join("app/assets/config/manifest.js"), %(//= link_tree ../../../javascript .js\n)
 
 say "Configure importmap paths in config/initializers/importmap.rb"
 create_file Rails.root.join("config/initializers/importmap.rb") do <<-RUBY
-# Configure import map to be used for ESM
 Rails.application.config.importmap.draw do
-  # All JavaScript files in the tree are mapped to their name
-  pin_all_from "app/assets/javascripts"
-
-  # Match libraries with their NPM package names for possibility of later porting.
-  # Ensure that libraries listed in the path have been linked in the asset pipeline manifest or precompiled.
-  pin "@rails/actioncable", to: "actioncable.esm.js"
-  pin "@rails/activestorage", to: "activestorage.esm.js"
-  pin "@rails/actiontext", to: "actiontext.js"
-  pin "trix", to: "trix.js"
-
-  # Use libraries directly from JavaScript CDNs
-  # pin "vue", to: "https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.esm.browser.js"
-  # pin "d3", to: "https://cdn.skypack.dev/pin/d3@v7.0.0-03vFl9bie0TSesDkWTJV/mode=imports/optimized/d3.js"
+  pin "application"
+
+  # Use libraries available via the asset pipeline (locally or via gems).
+  # pin "@rails/actioncable", to: "actioncable.esm.js"
+  # pin "@rails/activestorage", to: "activestorage.esm.js"
+
+  # Use libraries directly from JavaScript CDNs (see https://www.skypack.dev, https://cdnjs.com, https://www.jsdelivr.com/esm)
+  # pin "vue", to: "https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.esm.browser.js", preload: true
+  # pin "d3", to: "https://cdn.skypack.dev/pin/d3@v7.0.0-03vFl9bie0TSesDkWTJV/mode=imports/optimized/d3.js", preload: true
 
   # Pin vendored modules by first adding the following to app/assets/config/manifest.js:
   # //= link_tree ../../../vendor/assets/javascripts .js

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: importmap-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-14 00:00:00.000000000 Z
+date: 2021-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails