Download the PHP package tonysm/importmap-laravel without Composer
On this page you can find all versions of the php package tonysm/importmap-laravel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download tonysm/importmap-laravel
More information about tonysm/importmap-laravel
Files in tonysm/importmap-laravel
Package importmap-laravel
Short Description Use ESM with importmap to manage modern JavaScript in Laravel without transpiling or bundling.
License MIT
Homepage https://github.com/tonysm/importmap-laravel
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package importmap-laravel
Introduction
Use ESM with importmap to manage modern JavaScript in Laravel without transpiling or bundling.
Inspiration
This package was inspired by the Importmap Rails gem. Some pieces of this README were copied straight from there and adapted to the Laravel version.
How does it work?
Import maps let you import JavaScript modules using logical names that map to versioned/digested files – directly from the browser. So you can build modern JavaScript applications using JavaScript libraries made for ES modules (ESM) without the need for transpiling or bundling. 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. If you need to work with legacy browsers without native support, you may want to explore using the shim available.
Installation
You can install the package via Composer:
The package has an install command that you may run to replace the default Laravel scaffold with one to use importmap:
Next, we need to add the following component to our view or layout file:
Add that between your <head> 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:
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 on local environments. For production, it's recommended to run the importmap:optimize command instead:
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 presence over your pins. If you run that by accident in development, make sure you delete that file or simply run php artisan importmap:clear, which should get rid of it. You may also want to add /public/dist to your .gitignore file, as well as *importmap-manifest.json.
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:
Then, in your JavaScript files you can safely do:
Pinning Local Files
Local pins should be added to the routes/importmap.php file manually, like so:
This means that the app module will point to /js/app.js in the browser. This is the URI the browser will use to fetch the file, not the path to the file itself. Pins to local files assume a relative path of resources/js/ to find them.
Pinning Local Directories
Declaring all your local files can be tedious, so you may want to map an entire folder like so:
When we're generating the importmap JSON, we'll scan that directory looking for any .js or .jsm files inside of it and generating the correct importmap for them based on their relative location. There are a couple of interesting rules, though, something like:
| Path | Module | URI |
|---|---|---|
resources/js/app.js |
app |
/js/app.js |
resources/js/controllers/hello_controller.js |
controllers/hello_controller |
/js/controllers/hello_controller.js |
resources/js/libs/index.js |
libs |
/js/libs/index.js |
If there's an index.js file in a folder, we won't get index in the module name, so we can import it like
Instead of
Pinning External Dependencies
If you depend on any external library you can use the importmap:pin command to pin it, like so:
It will download the alpinejs lib, then it will add the following line to your routes/importmap.php file:
The pin command makes use of the jspm.io API to resolve the dependencies (and the dependencies of our dependencies), looking for ESM modules that we can pin, and resolving it to a CDN URL and downloading as a dependency. We can control the CDN we want to use by specifying the --from flag like so:
This will download the lib from unpkg instead of the default JSPM CDN.
It's important to note that the pin command will always resolve the dependencies (and the dependencies of our dependencies) and download all the files to your resources/js/vendor folder, which you should add to your version control and vendor it yourself. The pin will look like this:
The version is added as a comment to your pin so you know which version was imported. Don't remove that as it's gonna be useful later on when you need to upgrade your dependencies.
Preloading Modules
To avoid 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 by default. If you don't want to preload a dependency, because you want to load it on-demand for efficiency, append preload: false to the pin.
Which will add the correct links tags to your head tag in the HTML document, like so:
Dependency Maintenance Commands
Maintaining a healthy dependency list can be tricky. Here are a couple of commands to help you with this task.
Outdated Dependencies
To keep your dependencies up-to-date, make sure you run the importmap:outdated command from time to time:
This command will scan your routes/importmap.php file, find your current versions, then use the NPM registry API to look for the latest version of the packages you're using. It also handles locally served vendor libs that you added using the --download flag from the importmap:pin command.
Auditing Dependencies
If you want a security audit on your dependencies to see if you're using a version that's been breached, run the importmap:audit command from time to time. Better yet, add that command to your CI build:
This will also scan your routes/importmap.php file, find your current versions, then use the NPM registry API to look for vulnerabilities in your packages. It also handles locally served vendor libs that you added using the --download flag from the importmap:pin command.
Known Problems
On React's JSX and Vue's SFC
It's possible to use both React and Vue with importmaps but, unfortunately, you would have to use those without the power of JSX or SFC. That's because those file types need a compilation/transpilation step where they are converted to something the browser can understand. There are alternative ways to use both these libraries, but I should say that these are not "common" ways in their communities. You may use React with HTM. And you can use Vue just fine without SFC, the only difference is that your templates would be in Blade files, not a SFC file.
Process ENV Configs
You may be used to having a couple process.env.MIX_* lines in your JS files here and there. The way this works is Webpack would replace at build time your calls to process.env with the values it had during the build. Since we don't have a "build time" anymore, this won't work. Instead, you should add <meta> tags to your layout file with anything that you want to make available to your JavaScript files and use document.head.querySelector('meta[name=my-config]').content instead of relying on the process.env.
Consider using something like current.js to easily consume your <meta> configs using a globally available Current object.
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
- Tony Messias
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of importmap-laravel with dependencies
illuminate/contracts Version ^10.0|^11.0
illuminate/support Version ^10.0|^11.0
spatie/laravel-package-tools Version ^1.9