5.6 KiB

Czysty Wina Historia

Installation

You can use Shoelace via CDN or by installing it locally.

CDN Installation (Recommended)

The easiest way to install Shoelace is with the CDN. A lightweight loader will be added to your page that registers components asynchronously as you use them. It's like magic. ✨

Just add the following tags to your page.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace/shoelace.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace/shoelace.esm.js"></script>

Now you can start using Shoelace!

Local Installation

If you don't want to use the CDN, you can install Shoelace locally with the following command.

npm install @shoelace-style/shoelace

It's up to you to make the source files available to your app. One way to do this is to create a route in your app called /assets/shoelace that serves static files from node_modules/@shoelace-style/shoelace.

Once you've done that, add the following tags to your page. Make sure to update href and src so they point to the route you created.

<link rel="stylesheet" href="/assets/shoelace/shoelace.css">
<script type="module" src="/assets/shoelace/shoelace.esm.js"></script>

Importing Custom Elements

A custom elements bundle is available so you can import components and register them individually. This is a more flexible alternative to the lazy loading approach, but it requires the use of a bundler such as webpack or Rollup. You'll also need to manage static assets on your own.

Instructions vary depending on the bundler you're using.

Using webpack

To use the custom elements bundle with webpack, install Shoelace first.

npm install @shoelace-style/shoelace

Your webpack.config.js should look something like what's shown below. Note how assets such as icons are copied from node_modules to dist/icons via the CopyPlugin utility.

const path = require('path');
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader']
      },
    ],
  },
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, 'node_modules/@shoelace-style/shoelace/dist/shoelace/icons'),
          to: path.resolve(__dirname, 'dist/icons')
        }
      ]
    })
  ]
};

Next, import the components you want to use and set the assets directory.

import '@shoelace-style/shoelace/dist/shoelace/shoelace.css';
import { setAssetPath, SlButton, SlDropdown } from '@shoelace-style/shoelace';

setAssetPath(document.currentScript.src);
customElements.define('sl-button', SlButton);
customElements.define('sl-dropdown', SlDropdown);

For convenience, the bundle also exports a defineCustomElements() method. When this method is called, it will register all Shoelace components in the bundle.

import '@shoelace-style/shoelace/dist/shoelace/shoelace.css';
import { defineCustomElements, setAssetPath } from '@shoelace-style/shoelace';

setAssetPath(document.currentScript.src);
defineCustomElements();

While convenient for prototyping, importing all components will make your bundle larger. For best results, only import the components you're actually using.

?> An example webpack project is also available on GitHub for your convenience.

Using Rollup

To use the custom elements bundle with Rollup, install Shoelace first.

npm install @shoelace-style/shoelace

Your rollup.config.js should look something like what's shown below. Note how assets such as icons are copied from node_modules to dist/icons via the rollup-copy-plugin.

import path from 'path';
import commonjs from '@rollup/plugin-commonjs';
import copy from 'rollup-plugin-copy';
import postcss from 'rollup-plugin-postcss';
import resolve from '@rollup/plugin-node-resolve';

export default {
  input: 'src/index.js',
  output: [{ dir: path.resolve('dist/'), format: 'es' }],
  plugins: [
    resolve(),
    commonjs(),
    postcss({
      extensions: ['.css']
    }),
    copy({
      targets: [
        {
          src: path.resolve(__dirname, 'node_modules/@shoelace-style/shoelace/dist/shoelace/icons'),
          dest: path.resolve(__dirname, 'dist')
        }
      ]
    })
  ]
};