class AssetPipeline::ImportMap

Overview

The ImportMap is the main way that javascript is handled. This is a no-bundle approach using the "import map" browser standard.

The ImportMap supports several features that are provided by the import map specification:

Enhanced in Phase 4 with metadata support for categorizing imports by type and framework.

Defined in:

import_map/import_map.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(name : String = "application", public_asset_base_path : Path = Path["/"]) #

Set the name of the import map during initialization. The default is application Set the base path for your assets. This is used to make sure that relative paths are correct.

For example, if you're serving your javascript files from /assets/js then you would set public_asset_bate_path to /assets/js


[View source]

Instance Method Detail

def add_import(name : String, to : String, preload : Bool = false) #

Name the library you want to incude in the import map.

import("lodash", "https://cdn.jsdelivr.net/npm/lodash/lodash.min.js")

Adding preload will mark the module to be eager loaded by the browser.

import("lodash", "https://cdn.jsdelivr.net/npm/lodash/lodash.min.js", preload: true)

The #name should match the way you import a class in your JS code.

The to parameter is the full path and name of file or the full CDN url to an ESM module.

Think of it like this: you are importing the class #name associated to a library file path.


[View source]
def add_import_with_metadata(name : String, to : String, preload : Bool = false, type : String | Nil = nil, framework : String | Nil = nil) #

Enhanced import method with metadata support for categorizing imports by type and framework

import_map.add_import_with_metadata("HelloController", "hello_controller.js", 
                                    type: "controller", framework: "stimulus")

Supported types: "controller", "library", "utility", "framework", "component" Supported frameworks: "stimulus", "alpine", "vue", "react", nil (for framework-agnostic)


[View source]
def add_scope(scope : String, name : String, to : String) #

Add a scope to your import map. Scopes are paths relative to your application.

To learn how to use scopes, read about import maps and scopes here


[View source]
def auto_categorize_imports! #

Auto-detects and categorizes imports based on naming patterns

This method analyzes existing imports and adds metadata based on common patterns:

  • Names ending in "Controller" → type: "controller", framework: "stimulus"
  • Framework names (@hotwired/stimulus, alpinejs, etc.) → type: "framework"
  • Known utility libraries → type: "library"
import_map.auto_categorize_imports!

[View source]
def build_import_map_json : String #

Generates the valid import json. This can be used in a .json file or a <script type="importmap"> tag.


[View source]
def build_import_map_tag : String #

This renders the complete HTML tag for the import map, including the modulepreload tags required.

Use this method to render the full import map into an HTML view.


[View source]
def framework_agnostic_imports : Array(Hash(String, String | Bool)) #

Returns imports that have no framework specified (framework-agnostic)

import_map.framework_agnostic_imports  # Returns general/utility imports

[View source]
def import_summary : Hash(String, Hash(String, Int32)) #

Returns a summary of import types and frameworks in the import map

import_map.import_summary
# => {
#   types: {"controller" => 3, "library" => 2, "framework" => 1},
#   frameworks: {"stimulus" => 4, "alpine" => 1}
# }

[View source]
def imports_by_framework(framework : String) : Array(Hash(String, String | Bool)) #

Returns imports filtered by framework (e.g., "stimulus", "alpine", "vue")

import_map.imports_by_framework("stimulus")  # Returns only Stimulus-related imports

[View source]
def imports_by_type(type : String) : Array(Hash(String, String | Bool)) #

Returns imports filtered by type (e.g., "controller", "library", "utility")

import_map.imports_by_type("controller")  # Returns only controller imports

[View source]
def name : String #

The name of your import map. Updatable with the #name= method.


[View source]
def name=(name : String) #

The name of your import map. Updatable with the #name= method.


[View source]
def stimulus_controller_imports : Array(Hash(String, String | Bool)) #

Returns stimulus controller imports specifically

Convenience method that combines type="controller" and framework="stimulus" filtering


[View source]