4.9 KiB

Czysty Wina Historia

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.17
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/bootstrap.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/bootstrap.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/bootstrap.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!

4.9 KiB Czysty Wina Historia