PHPackages                             tonysm/importmap-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tonysm/importmap-laravel

ActiveLibrary[Utility & Helpers](/categories/utility)

tonysm/importmap-laravel
========================

Use ESM with importmap to manage modern JavaScript in Laravel without transpiling or bundling.

2.6.0(3mo ago)151410.6k↓52%5[2 issues](https://github.com/tonysm/importmap-laravel/issues)1MITPHPPHP ^8.2CI passing

Since Jan 27Pushed 1w ago3 watchersCompare

[ Source](https://github.com/tonysm/importmap-laravel)[ Packagist](https://packagist.org/packages/tonysm/importmap-laravel)[ Docs](https://github.com/tonysm/importmap-laravel)[ GitHub Sponsors](https://github.com/tonysm)[ RSS](/packages/tonysm-importmap-laravel/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (20)Versions (45)Used By (1)

[![Logo Importmap Laravel](/art/importmap-laravel-logo.svg)](/art/importmap-laravel-logo.svg)

 [![Total Downloads](https://camo.githubusercontent.com/c9c8b1a28808e8772c292023b906b89e08b12e2b9394d89d9a8e5718b39a8831/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746f6e79736d2f696d706f72746d61702d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tonysm/importmap-laravel) [![Latest Stable Version](https://camo.githubusercontent.com/24a8c5b77265f1adc7c207e8d4dfb9ebfb1d6dc26496a6e9bd7bcbb164235126/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f6e79736d2f696d706f72746d61702d6c61726176656c)](https://packagist.org/packages/tonysm/importmap-laravel) [![License](https://camo.githubusercontent.com/87af1ee3bdfc1b88ed0cb38728ac5a5a69b5759508febf96f1d58be42fdf8b85/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746f6e79736d2f696d706f72746d61702d6c61726176656c)](https://packagist.org/packages/tonysm/importmap-laravel)

Introduction
------------

[](#introduction)

Use ESM with importmap to manage modern JavaScript in Laravel without transpiling or bundling.

### Inspiration

[](#inspiration)

This package was inspired by the [Importmap Rails](https://github.com/rails/importmap-rails) gem. Some pieces of this README were copied straight from there and adapted to the Laravel version.

### How does it work?

[](#how-does-it-work)

[Import maps](https://github.com/WICG/import-maps) lets you import JavaScript modules directly from the browser using logical names that map to versioned/digested files. So you can [build modern JavaScript applications using JavaScript libraries made for ES modules (ESM) without the need for transpiling or bundling](https://world.hey.com/dhh/modern-web-apps-without-javascript-bundling-or-transpiling-a20f2755). This frees you from needing Webpack, Yarn, npm, or any other part of the JavaScript toolchain.

With this approach, you'll ship many small JavaScript files instead of one big JavaScript file. Thanks to HTTP/2 that no longer carries a material performance penalty during the initial transport, and offers substantial benefits over the long run due to better caching dynamics. Whereas before any change to any JavaScript file included in your big bundle would invalidate the cache for the whole bundle, now only the cache for that single file is invalidated.

[Import maps are supported natively in all major, modern browsers](https://caniuse.com/?search=importmap). If you need to work with legacy browsers without native support, you may want to explore using [the shim available](https://github.com/guybedford/es-module-shims).

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require tonysm/importmap-laravel
```

The package has an `install` command that you may run to replace the default Laravel scaffold with one to use importmap:

```
php artisan importmap:install
```

Next, we need to add the following component to our view or layout file:

```

```

Add that between your `` tags. The `entrypoint` should be the "main" file, commonly the `resources/js/app.js` file, which will be mapped to the `app` module (use the module name, not the file).

By default, the `x-importmap::tags` component assumes your entrypoint module is `app`, which matches the existing `resources/js/app.js` file from Laravel's default scaffolding. You may want to customize the entrypoint, which you can do with the `entrypoint` prop:

```

```

The package will automatically map the `resources/js` folder to your `public/js` folder using Laravel's symlink feature. All you have to do after installing the package is run:

```
php artisan storage:link
```

If you're using Laravel Sail, make sure you prefix that command with `sail` as the symlink needs to be created inside the container.

The symlink is only registered in local environments. For production, it's recommended to run the `importmap:optimize` command instead:

```
php artisan importmap:optimize
```

This should scan all your pinned files/folders (no URLs) and publish them to `public/dist/js`, adding a digest based on the file's content to the file name - so something like `public/dist/js/app-123123.js`, and then generate a `.importmap-manifest.json` file in the `public/` folder. This file will get precedence over your pins. If you run that by accident in development, manually delete that file or run `php artisan importmap:clear`, which should delete it for you. You may also want to add the `/public/dist` path and the `*importmap-manifest.json` file to your `.gitignore` file.

Usage
-----

[](#usage)

In a nutshell, importmap works by giving the browser a map of where to look for your JavaScript import statements. For instance, you could *pin* a dependency in the `routes/importmap.php` file for Alpinejs like so:

```