README

Alto ImportMap is a PHP library to build, validate, and render import maps in PHP for web applications. It supports imports, scopes and integrity metadata, and includes a resolver aligned with the WICG resolution algorithm.

Installation

composer require alto/importmap

Basic Usage

1. Create an ImportMap

You can build an ImportMap manually or by adding entries.

use Alto\ImportMap\ImportMap;

$map = new ImportMap();

// Add a simple mapping
$map->add('react', 'https://esm.sh/react@18.2.0');
$map->add('react-dom', 'https://esm.sh/react-dom@18.2.0');

2. Load from File (Optional)

You can also load an existing import map from a JSON file.

$map = ImportMap::fromFile(__DIR__ . '/importmap.json');

// You can still add entries dynamically
$map->add('app', '/js/app.js');

3. Render to HTML

Use the HtmlRenderer to generate the <script type="importmap"> tag. It also supports modulepreload links for performance.

use Alto\ImportMap\Renderer\HtmlRenderer;

$renderer = new HtmlRenderer();

// Render the import map script and preload links
echo $renderer->render($map);

Output:

<script type="importmap">
    {"imports":{"react":"https:\/\/esm.sh\/react@18.2.0","react-dom":"https:\/\/esm.sh\/react-dom@18.2.0"}}
</script>
<link rel="modulepreload" href="https://esm.sh/react@18.2.0">
<link rel="modulepreload" href="https://esm.sh/react-dom@18.2.0">

Advanced Features

Scoped Imports

You can define imports that only apply to specific scopes (paths).

// Available globally
$map->add('lodash', 'https://unpkg.com/lodash-es@4.17.21/lodash.js');

// Different version for a specific scope
$map->add(
    'lodash', 
    'https://unpkg.com/lodash-es@3.10.1/lodash.js', 
    scope: '/legacy/'
);

Integrity Hashes

Ensure security by adding integrity hashes (SRI) to your entries. The renderer includes these in the import map. The Resolver can also use them, and you can access them via the $map->integrity property if needed for other tags.

$map->add(
    'app', 
    '/js/app.js', 
    integrity: 'sha384-...'
);

Merging Maps

You can combine multiple maps, which is useful for modular applications.

$coreMap = new ImportMap(['react' => '...']);
$pluginMap = new ImportMap(['plugin-ui' => '...']);

$coreMap->merge($pluginMap);

Resolving Imports

The NativeResolver implements the WICG Import Maps resolution algorithm. This allows you to resolve a specifier to a URL within your PHP application (e.g., for bundling or server-side rendering).

use Alto\ImportMap\Resolver\NativeResolver;

$resolver = new NativeResolver();

try {
    $resolution = $resolver->resolve('react', $map);
    // ['url' => 'https://esm.sh/react@18.2.0', 'integrity' => null]
    
    echo $resolution['url']; 
} catch (ResolutionFailedException $e) {
    // Handle error
}

Documentation

• Installation: install the package and verify its requirements.
• Getting started: build and render a first import map.
• Imports: define and resolve exact, prefix, and scoped imports.
• Packages: load and combine maps contributed by packages.
• Output: generate safe import-map and module-preload tags.
• Caching: cache generated output without hiding map changes.
• Errors: recover from invalid entries, files, and resolutions.
• Complete documentation: review the package scope and every guide.

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation.

Support

ALTO ImportMap is open source and independently maintained by Simon André. If it is useful to your work, you can support its continued development through GitHub Sponsors.

Sharing the package or starring it on GitHub also helps.

License

ALTO ImportMap is released by ALTO PHP under the MIT License.