Serving

Composing import maps

Combine several import map files — an engine's pins with the application's — through config.importmap.paths.

config.importmap.paths#

By default Rails loads the import map definition from the application's config/importmap.rb into the Importmap::Map at Rails.application.importmap. Any additional file appended to Rails.application.config.importmap.paths is drawn into the same map, in order. Files added in config/application.rb or an environment file come before config/importmap.rb, which the engine appends to the list during initialization. A later pin overrides an earlier pin of the same name. Directories are expanded on top of the explicit pins when the map is rendered, so a file found by pin_all_from wins over a pin of the same name whichever file declared it.

Pinning from an engine#

An engine appends its own config/importmap.rb before the importmap initializer runs, and pins its JavaScript from its own asset directory:

my_engine/lib/my_engine/engine.rb

module MyEngine
  class Engine < ::Rails::Engine
    # ...
    initializer "my-engine.importmap", before: "importmap" do |app|
      app.config.importmap.paths << Engine.root.join("config/importmap.rb")
      # ...
    end
  end
end

my_engine/config/importmap.rb

pin_all_from File.expand_path("../app/assets/javascripts", __dir__)

An engine that wants its import map reloaded in development also appends its JavaScript directory to config.importmap.cache_sweepers — see Caching & ETags.