importmap-rails 0.1.3 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +35 -8
  3. data/app/assets/javascripts/es-module-shims@0.12.2.js +3 -0
  4. data/app/helpers/importmap/importmap_tags_helper.rb +17 -4
  5. data/lib/importmap/engine.rb +10 -4
  6. data/lib/importmap/map.rb +97 -0
  7. data/lib/importmap/version.rb +1 -1
  8. data/lib/install/install.rb +15 -18
  9. metadata +3 -3
  10. data/lib/importmap/paths.rb +0 -63
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e9569cf8ada42f3b40596da6bbb24565237a45f3f49108b91470d18715d6fe55
4
- data.tar.gz: 682592d777e3fffa178e4b0f74fc97c83564f4222a881532376a26890faa12da
3
+ metadata.gz: 0ec141d17e7859eac9dae9d91c47f04957f650f2cef7eeae7cc0449b9c92cd89
4
+ data.tar.gz: a2ce05f0a9c340668d407f5c7e2cf64b2fe68f262e567ab94fb1ccc029b10487
5
5
  SHA512:
6
- metadata.gz: 6ff7b0f6d2f5510281a6f540096b03dd7dc760927edf229425c1b5032b93e88ae17276fc9b348c7777cff0eacf39b58e944db26169d11db44c35c75185b89384
7
- data.tar.gz: 9456a86bc8264595860b0e0e03690c82f9fb739f1a5a4ea7850f59f7570daec22c42ba18d6fde9fd5bc5cc76d4b310c6d4e172c4a5dfe8b18ef98d0a7e597dae
6
+ metadata.gz: e692f3214ec9f899ebffd3f239a8f87202811b8098de1f2b2906bcb2558d446801a34fe359b3a94b8b8768220d54918f089ed8149ede3e04708d29f435314872
7
+ data.tar.gz: 89eafbbd709cd3e9eb2e97310c96297465bb935b713e841c8b8f7c9dd4a7d4f59c05b0d5720f0d9087dfbcb3a7e86d17c6d89a6c061622c9b8e6387719707795
data/README.md CHANGED
@@ -13,14 +13,14 @@ There's [native support for import maps in Chrome/Edge 89+](https://caniuse.com/
13
13
  2. Run `./bin/bundle install`
14
14
  3. Run `./bin/rails importmap:install`
15
15
 
16
- 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`.
16
+ 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/importmap.rb`.
17
17
 
18
18
  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.
19
19
 
20
20
 
21
21
  ## Usage
22
22
 
23
- 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.)
23
+ The import map is configured programmatically through the `Rails.application.config.importmap` assignment, which by default is setup in `config/initializers/importmap.rb` after running the installer. (Note that since this is a config initializer, you must restart your development server after making any changes.)
24
24
 
25
25
  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.
26
26
 
@@ -31,7 +31,7 @@ It makes sense to use logical names that match the package names used by NPM, su
31
31
 
32
32
  ## Use with Hotwire
33
33
 
34
- This gem was designed for use with [Hotwire](https://hotwired.dev) in mind. The Hotwire gems, like [turbo-rails](https://github.com/hotwired/turbo-rails) and [stimulus-rails](https://github.com/hotwired/stimulus-rails) (both bundled as [hotwire-rails](https://github.com/hotwired/hotwire-rails)), are automatically configured for use with `importmap-rails`. This means you won't have to manually setup the path mapping in `config/initializers/assets.rb`, and instead can simply refer to the logical names directly in your `app/assets/javascripts/application.js`, like so:
34
+ This gem was designed for use with [Hotwire](https://hotwired.dev) in mind. The Hotwire gems, like [turbo-rails](https://github.com/hotwired/turbo-rails) and [stimulus-rails](https://github.com/hotwired/stimulus-rails) (both bundled as [hotwire-rails](https://github.com/hotwired/hotwire-rails)), are automatically configured for use with `importmap-rails`. This means you won't have to manually setup the path mapping in `config/initializers/importmap.rb`, and instead can simply refer to the logical names directly in your `app/assets/javascripts/application.js`, like so:
35
35
 
36
36
  ```js
37
37
  import "@hotwired/turbo-rails"
@@ -41,12 +41,12 @@ import "@hotwired/stimulus-autoloader"
41
41
 
42
42
  ## Use with Skypack (and other CDNs)
43
43
 
44
- 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:
44
+ 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/importmap.rb` with the URL instead of the local path:
45
45
 
46
46
  ```ruby
47
- Rails.application.config.importmap.paths.tap do |paths|
48
- paths.asset "trix", path: "https://cdn.skypack.dev/trix"
49
- paths.asset "md5", path: "https://cdn.skypack.dev/md5"
47
+ Rails.application.config.importmap.draw do
48
+ pin "trix", to: "https://cdn.skypack.dev/trix"
49
+ pin "md5", to: "https://cdn.skypack.dev/md5"
50
50
  end
51
51
  ```
52
52
 
@@ -56,7 +56,34 @@ Now you can use these in your application.js entrypoint like you would any other
56
56
  import "trix"
57
57
  import md5 from "md5"
58
58
  console.log(md5("Hash it out"))
59
- ```
59
+ ```
60
+
61
+
62
+ ## Preloading pinned modules
63
+
64
+ 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`.
65
+
66
+ Example:
67
+
68
+ ```ruby
69
+ # config/initializers/importmap.rb
70
+ Rails.application.config.importmap.draw do
71
+ pin "trix", to: "https://cdn.skypack.dev/trix"
72
+ pin "md5", to: "https://cdn.skypack.dev/md5", preload: false
73
+ end
74
+
75
+ # app/views/layouts/application.html.erb
76
+ <%= javascript_importmap_tags %>
77
+
78
+ # will include the following link before the importmap is setup:
79
+ <link rel="modulepreload" href="https://cdn.skypack.dev/trix">
80
+ ...
81
+ ```
82
+
83
+
84
+ ## Caching the import map and preload modules
85
+
86
+ 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.
60
87
 
61
88
 
62
89
  ## Expected errors from using the es-module-shim
data/app/assets/javascripts/es-module-shims@0.12.2.js CHANGED
@@ -1,5 +1,8 @@
1
1
  /* ES Module Shims 0.12.2 */
2
2
  (function () {
3
+ // Temporary hack around https://github.com/guybedford/es-module-shims/issues/148
4
+ if (navigator.userAgent.match("Chrome")) return
5
+
3
6
  const resolvedPromise = Promise.resolve();
4
7
 
5
8
  let baseUrl;
data/app/helpers/importmap/importmap_tags_helper.rb CHANGED
@@ -2,16 +2,17 @@ module Importmap::ImportmapTagsHelper
2
2
  # Setup all script tags needed to use an importmap-powered entrypoint (which defaults to application.js)
3
3
  def javascript_importmap_tags(entry_point = "application")
4
4
  safe_join [
5
+ javascript_importmap_module_preload_tags,
5
6
  javascript_inline_importmap_tag,
6
7
  javascript_importmap_shim_tag,
7
8
  javascript_import_module_tag(entry_point)
8
9
  ], "\n"
9
10
  end
10
11
 
11
- # Generate an inline importmap tag using the passed `importmap_paths` object to produce the JSON map.
12
- # By default, `Rails.application.config.importmap.paths` is used for this object,
13
- def javascript_inline_importmap_tag(importmap_paths = Rails.application.config.importmap.paths)
14
- tag.script(importmap_paths.to_json(self).html_safe, type: "importmap", "data-turbo-track": "reload")
12
+ # Generate an inline importmap tag using the passed `importmap_json` JSON string.
13
+ # By default, `Rails.application.config.importmap.to_json(resolver: self)` is used.
14
+ def javascript_inline_importmap_tag(importmap_json = Rails.application.config.importmap.to_json(resolver: self))
15
+ tag.script(importmap_json.html_safe, type: "importmap", "data-turbo-track": "reload")
15
16
  end
16
17
 
17
18
  # 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
23
24
  def javascript_import_module_tag(module_name)
24
25
  tag.script %(import "#{module_name}").html_safe, type: "module"
25
26
  end
27
+
28
+ # Link tags for preloading all modules marked as preload: true in the `importmap`
29
+ # (defaults to Rails.application.config.importmap), such that they'll be fetched
30
+ # in advance by browsers supporting this link type (https://caniuse.com/?search=modulepreload).
31
+ def javascript_importmap_module_preload_tags(importmap = Rails.application.config.importmap)
32
+ javascript_module_preload_tag *importmap.preloaded_module_paths(resolver: self)
33
+ end
34
+
35
+ # Link tag(s) for preloading the JavaScript module residing in `*paths`. Will return one link tag per path element.
36
+ def javascript_module_preload_tag(*paths)
37
+ safe_join(Array(paths).collect { |path| tag.link rel: "modulepreload", href: path }, "\n")
38
+ end
26
39
  end
data/lib/importmap/engine.rb CHANGED
@@ -1,15 +1,15 @@
1
- require "importmap/paths"
1
+ require "importmap/map"
2
2
 
3
3
  module Importmap
4
4
  class Engine < ::Rails::Engine
5
- config.importmap = ActiveSupport::OrderedOptions.new
6
- config.importmap.paths = Importmap::Paths.new.tap { |paths| paths.assets_in "app/assets/javascripts" }
5
+ config.importmap = Importmap::Map.new
7
6
 
8
7
  config.autoload_once_paths = %W( #{root}/app/helpers )
9
8
 
10
9
  initializer "importmap.assets" do
11
10
  if Rails.application.config.respond_to?(:assets)
12
- Rails.application.config.assets.precompile += %w( es-module-shims )
11
+ Rails.application.config.assets.precompile += %w( es-module-shims.js )
12
+ Rails.application.config.assets.paths << Rails.root.join("app/javascript")
13
13
  end
14
14
  end
15
15
 
@@ -18,5 +18,11 @@ module Importmap
18
18
  helper Importmap::ImportmapTagsHelper
19
19
  end
20
20
  end
21
+
22
+ initializer "importmap.caching" do |app|
23
+ if Rails.application.config.importmap.cached.nil?
24
+ Rails.application.config.importmap.cached = app.config.action_controller.perform_caching
25
+ end
26
+ end
21
27
  end
22
28
  end
data/lib/importmap/map.rb ADDED
@@ -0,0 +1,97 @@
1
+ class Importmap::Map
2
+ attr_reader :files, :directories
3
+ attr_accessor :cached
4
+
5
+ def initialize
6
+ @files, @directories = {}, {}
7
+ end
8
+
9
+ def draw(&block)
10
+ instance_eval(&block)
11
+ end
12
+
13
+ def pin(name, to: nil, preload: true)
14
+ @files[name] = MappedFile.new(name: name, path: to || "#{name}.js", preload: preload)
15
+ end
16
+
17
+ def pin_all_from(path, under: nil, preload: true)
18
+ @directories[path] = MappedDir.new(path: path, under: under, preload: preload)
19
+ end
20
+
21
+ def preloaded_module_paths(resolver:)
22
+ cache_as(:preloaded_module_paths) do
23
+ resolve_asset_paths(expanded_preloading_files_and_directories, resolver: resolver).values
24
+ end
25
+ end
26
+
27
+ def to_json(resolver:)
28
+ cache_as(:json) do
29
+ { "imports" => resolve_asset_paths(expanded_files_and_directories, resolver: resolver) }.to_json
30
+ end
31
+ end
32
+
33
+ private
34
+ MappedFile = Struct.new(:name, :path, :preload, keyword_init: true)
35
+ MappedDir = Struct.new(:path, :under, :preload, keyword_init: true)
36
+
37
+ def cache_as(name)
38
+ if (cached && result = instance_variable_get("@cached_#{name}"))
39
+ result
40
+ else
41
+ instance_variable_set("@cached_#{name}", yield)
42
+ end
43
+ end
44
+
45
+ def resolve_asset_paths(paths, resolver:)
46
+ paths.transform_values do |mapping|
47
+ begin
48
+ resolver.asset_path(mapping.path)
49
+ rescue Sprockets::Rails::Helper::AssetNotFound
50
+ Rails.logger.warn "Importmap skipped missing path: #{mapping.path}"
51
+ nil
52
+ end
53
+ end.compact
54
+ end
55
+
56
+ def expanded_preloading_files_and_directories
57
+ expanded_files_and_directories.select { |name, mapping| mapping.preload }
58
+ end
59
+
60
+ def expanded_files_and_directories
61
+ @files.dup.tap { |expanded| expand_directories_into expanded }
62
+ end
63
+
64
+ def expand_directories_into(paths)
65
+ @directories.values.each do |mapping|
66
+ if (absolute_path = absolute_root_of(mapping.path)).exist?
67
+ find_javascript_files_in_tree(absolute_path).each do |filename|
68
+ module_filename = filename.relative_path_from(absolute_path)
69
+ module_name = module_name_from(module_filename, mapping.under)
70
+ module_path = mapping.under ? absolute_path.basename.join(module_filename).to_s : module_filename.to_s
71
+
72
+ paths[module_name] = MappedFile.new(name: module_name, path: module_path, preload: mapping.preload)
73
+ end
74
+ end
75
+ end
76
+ end
77
+
78
+ # Strip off the extension, /index, or any versioning data for an absolute module name.
79
+ def module_name_from(filename, under)
80
+ filename_without_ext = filename.to_s.remove(filename.extname)
81
+
82
+ if filename_without_ext == "index" && under
83
+ under
84
+ else
85
+ module_name = filename_without_ext.split("@").first
86
+ under ? "#{under}/#{module_name}" : module_name
87
+ end
88
+ end
89
+
90
+ def find_javascript_files_in_tree(path)
91
+ Dir[path.join("**/*.js{,m}")].collect { |file| Pathname.new(file) }.select(&:file?)
92
+ end
93
+
94
+ def absolute_root_of(path)
95
+ (pathname = Pathname.new(path)).absolute? ? pathname : Rails.root.join(path)
96
+ end
97
+ end
data/lib/importmap/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module Importmap
2
- VERSION = "0.1.3"
2
+ VERSION = "0.2.3"
3
3
  end
data/lib/install/install.rb CHANGED
@@ -9,8 +9,8 @@ else
9
9
  end
10
10
 
11
11
  say "Create application.js module as entrypoint"
12
- create_file Rails.root.join("app/assets/javascripts/application.js") do <<-JS
13
- // Configure your import map in config/initializers/assets.rb
12
+ create_file Rails.root.join("app/javascript/application.js") do <<-JS
13
+ // Configure your import map in config/initializers/importmap.rb
14
14
 
15
15
  // import "@rails/actioncable"
16
16
  // import "@rails/activestorage"
@@ -18,27 +18,24 @@ JS
18
18
  end
19
19
 
20
20
  say "Ensure JavaScript files are in the asset pipeline manifest"
21
- append_to_file Rails.root.join("app/assets/config/manifest.js"), %(//= link_tree ../javascripts .js\n)
21
+ append_to_file Rails.root.join("app/assets/config/manifest.js"), %(//= link_tree ../../../javascript .js\n)
22
22
 
23
- say "Configure importmap paths in config/initializers/assets.rb"
24
- append_to_file Rails.root.join("config/initializers/assets.rb") do <<-RUBY
23
+ say "Configure importmap paths in config/initializers/importmap.rb"
24
+ create_file Rails.root.join("config/initializers/importmap.rb") do <<-RUBY
25
+ Rails.application.config.importmap.draw do
26
+ pin "application"
25
27
 
26
- # Configure import map beyond the default of having all files in app/assets/javascripts mapped.
27
- Rails.application.config.importmap.paths.tap do |paths|
28
- # Match libraries with their NPM package names for possibility of later porting.
29
- # Ensure that libraries listed in the path have been linked in the asset pipeline manifest or precompiled.
30
- paths.asset "@rails/actioncable", path: "actioncable.esm.js"
31
- paths.asset "@rails/activestorage", path: "activestorage.esm.js"
32
- paths.asset "@rails/actiontext", path: "actiontext.js"
33
- paths.asset "trix"
28
+ # Use libraries available via the asset pipeline (locally or via gems).
29
+ # pin "@rails/actioncable", to: "actioncable.esm.js"
30
+ # pin "@rails/activestorage", to: "activestorage.esm.js"
34
31
 
35
- # Use libraries directly from JavaScript CDNs
36
- # paths.asset "vue", path: "https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.esm.browser.js"
37
- # paths.asset "d3", path: "https://cdn.skypack.dev/pin/d3@v7.0.0-03vFl9bie0TSesDkWTJV/mode=imports/optimized/d3.js"
32
+ # Use libraries directly from JavaScript CDNs (see https://www.skypack.dev, https://cdnjs.com, https://www.jsdelivr.com/esm)
33
+ # pin "vue", to: "https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.esm.browser.js", preload: true
34
+ # pin "d3", to: "https://cdn.skypack.dev/pin/d3@v7.0.0-03vFl9bie0TSesDkWTJV/mode=imports/optimized/d3.js", preload: true
38
35
 
39
- # Map vendored modules by first adding the following to app/assets/config/manifest.js:
36
+ # Pin vendored modules by first adding the following to app/assets/config/manifest.js:
40
37
  # //= link_tree ../../../vendor/assets/javascripts .js
41
- # paths.assets_in "vendor/assets/javascripts"
38
+ # pin_all_from "vendor/assets/javascripts"
42
39
  end
43
40
  RUBY
44
41
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: importmap-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.3
4
+ version: 0.2.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - David Heinemeier Hansson
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-08-14 00:00:00.000000000 Z
11
+ date: 2021-08-16 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rails
@@ -38,7 +38,7 @@ files:
38
38
  - app/helpers/importmap/importmap_tags_helper.rb
39
39
  - lib/importmap-rails.rb
40
40
  - lib/importmap/engine.rb
41
- - lib/importmap/paths.rb
41
+ - lib/importmap/map.rb
42
42
  - lib/importmap/version.rb
43
43
  - lib/install/install.rb
44
44
  - lib/shim.js
data/lib/importmap/paths.rb DELETED
@@ -1,63 +0,0 @@
1
- class Importmap::Paths
2
- attr_reader :files, :directories
3
-
4
- def initialize
5
- @files = {}
6
- @directories = {}
7
- end
8
-
9
- def asset(name, path: nil)
10
- @files[name] = path || "#{name}.js"
11
- end
12
-
13
- def assets_in(path, append_base_path: false)
14
- @directories[path] = append_base_path
15
- end
16
-
17
- def to_json(resolver)
18
- { "imports" => map_to_asset_paths(resolver) }.to_json
19
- end
20
-
21
- private
22
- def map_to_asset_paths(resolver)
23
- expanded_files_and_directories.transform_values do |path|
24
- begin
25
- resolver.asset_path(path)
26
- rescue Sprockets::Rails::Helper::AssetNotFound
27
- Rails.logger.warn "Importmap skipped missing asset: #{path}"
28
- nil
29
- end
30
- end.compact
31
- end
32
-
33
- def expanded_files_and_directories
34
- @files.dup.tap { |expanded| expand_directories_into expanded }
35
- end
36
-
37
- def expand_directories_into(paths)
38
- @directories.each do |(path, append_base_path)|
39
- if (absolute_path = absolute_root_of(path)).exist?
40
- find_javascript_files_in_tree(absolute_path).each do |filename|
41
- module_filename = filename.relative_path_from(absolute_path)
42
- module_name = module_name_from(module_filename)
43
- module_path = append_base_path ? absolute_path.basename.join(module_filename).to_s : module_filename.to_s
44
-
45
- paths[module_name] = module_path
46
- end
47
- end
48
- end
49
- end
50
-
51
- # Strip off the extension, /index, or any versioning data for an absolute module name.
52
- def module_name_from(filename)
53
- filename.to_s.remove(filename.extname).remove("/index").split("@").first
54
- end
55
-
56
- def find_javascript_files_in_tree(path)
57
- Dir[path.join("**/*.js{,m}")].collect { |file| Pathname.new(file) }.select(&:file?)
58
- end
59
-
60
- def absolute_root_of(path)
61
- (pathname = Pathname.new(path)).absolute? ? pathname : Rails.root.join(path)
62
- end
63
- end