4.9 KiB
Integrating with Laravel
This page explains how to integrate Shoelace with a Laravel app using a local Webpack bundle.
?> This is a community-maintained document. Please ask the community if you have questions about this integration. You can also suggest improvements to make it better.
Requirements
This integration has been tested with the following:
- Laravel >= 8
- Node >= 14
- Laravel Mix >= 6
Instructions
These instructions assume an out-of-the-box Laravel 8+ install that uses Laravel Mix to compile assets.
Be sure to run npm install
to install the default Laravel front-end dependencies before installing Shoelace.
Install the Shoelace package
npm install @shoelace-style/shoelace
Import the Default Theme
Import Shoelace's default theme (stylesheet) in /resources/css/app.css
:
@import "/node_modules/@shoelace-style/shoelace/dist/themes/light.css";
Import Your Shoelace Components
Import each Shoelace component you plan to use in /resources/js/boostrap.js
. Since Laravel Mix uses Webpack, use the full path to each component -- as outlined in the Cherry Picking instructions. You can find the full import statement for a component in the Importing section of the component's documentation (use the Bundler import). Your imports should look similar to:
import "@shoelace-style/shoelace/dist/components/button/button.js";
import "@shoelace-style/shoelace/dist/components/dialog/dialog.js";
import "@shoelace-style/shoelace/dist/components/drawer/drawer.js";
import "@shoelace-style/shoelace/dist/components/menu/menu.js";
import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js";
Set the Base Path
Add the base path to your Shoelace assets (icons, images, etc.) in /resources/js/boostrap.js
. The path must point to the same folder where you copy assets to in the next step.
import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js";
setBasePath("/");
Here's an example /resources/js/boostrap.js
file, after importing and setting the base path and components.
import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js";
setBasePath("/assets");
import "@shoelace-style/shoelace/dist/components/button/button.js";
import "@shoelace-style/shoelace/dist/components/dialog/dialog.js";
import "@shoelace-style/shoelace/dist/components/drawer/drawer.js";
import "@shoelace-style/shoelace/dist/components/menu/menu.js";
import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js";
Configure Laravel Mix
Laravel Mix is a wrapper around Webpack that simplifies configuration. Mix is used by default for compiling front-end assets in Laravel.
Modify webpack.mix.js
to add Shoelace's assets to Webpack's build process:
mix.js("resources/js/app.js", "public/js")
.postCss("resources/css/app.css", "public/css", [])
.copy("node_modules/@shoelace-style/shoelace/dist/assets", "public/assets")
Consider extracting vendor libraries to a separate file. This splits frequently updated vendor libraries (like Shoelace) from your front-end application code -- for better long-term caching.
Here's an example webpack.mix.js
file that compiles and splits your JS into app.js
and vendor.js
files, and builds an optimized CSS bundle using PostCSS.
mix.js("resources/js/app.js", "public/js")
.postCss("resources/css/app.css", "public/css", [])
.copy("node_modules/@shoelace-style/shoelace/dist/assets", "public/assets")
.extract(); // extracts libraries in node_modules to vendor.js
Compile Front-End Assets
Run the Laravel Mix npm scripts to build your application's CSS and JavaScript code.
## build a development bundle
npm run dev
## build a production bundle
npm run prod
Include Front-End Assets in Your Layout File
Most full-stack Laravel applications use layouts to define the basic structure of a page. After compiling your front-end assets (above), include them in your top-level layouts/templates. The following example uses the Laravel asset helper to generate a full URL.
<script defer src="{{ asset('js/manifest.js') }}"></script>
<script defer src="{{ asset('js/vendor.js') }}"></script>
<script defer src="{{ asset('/js/app.js') }}"></script>
<link href="{{ asset('css/app.css') }}" rel="stylesheet">
Have fun using Shoelace components in your Laravel app!