mirror of https://github.com/shoelace-style/webawesome.git synced 2026-01-12 12:09:26 +00:00

Files

Konnor Rogers 3e33fbb905 Docs/rails-integration (#238 )

* docs: add integrations file

* docs: tweak Rails integration

* fix: restore color-picker to original state

* docs: tweak integrations readme

2020-10-08 08:44:26 -04:00

3.4 KiB

Raw Blame History

Integrations

Rails

Requirements

Currently, this integration has been tested and working with the following:

Rails >= 6
Node >= 12.10
Webpacker >= 5

Getting Started

NPM packages

To get started using Shoelace with Rails you must first install the following packages:

yarn add @shoelace-style/shoelace copy-webpack-plugin

Importing Stylesheets

The next step is to import the Shoelace stylesheets in a file located at app/javascript/stylesheets/application.scss like so:

/* app/javascript/stylesheets/application.scss */

@import '~@shoelace-style/shoelace/dist/shoelace/shoelace';

Importing Javascript

After importing the stylesheet, you must now import the Javascript files for Shoelace.

To do so, navigate to the app/javascript/packs/application.js file and add the following code:

// app/javascript/packs/application.js

import '../stylesheets/application.scss'
import { defineCustomElements, setAssetPath } from '@shoelace-style/shoelace'

// ...

// This enables all web components for the current page
setAssetPath(document.currentScript.src)
defineCustomElements()

NOTE: The above code will import all shoelace web components for convenience. If you would like to selectively import components check out the Using Webpack section of the docs.

Webpack Config

Now that we have our stylesheets and javascript setup, we have to add Shoelace's icons to the final build output. To do so, we must modify the config/webpack/environment.js file like so:

// config/webpack/environment.js

const { environment } = require('@rails/webpacker')

// Shoelace config
const path = require('path')
const CopyPlugin = require('copy-webpack-plugin')

// Adds shoelace icons to Webpack's build process
environment.plugins.append(
  'CopyPlugin',
  new CopyPlugin({
    patterns: [
      {
        from: path.resolve(
          __dirname,
          '../../node_modules/@shoelace-style/shoelace/dist/shoelace/icons'
        ),
        to: path.resolve(__dirname, '../../public/packs/js/icons')
      }
    ]
  })
)

Adding pack tags

The final step to this process is to add the corresponding pack_tags to your app/views/layouts/application.html.erb file.

You should have the following tags in your app/views/layouts/application.html.erb in the <head> of the document, like so:

<!-- app/views/layouts/application.html.erb -->

<!DOCTYPE html>
<html>
  <head>
    <!-- above tags omitted -->

    <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>
  <body><%= yield %></body>
</html>

And that's it! You can start using Shoelace Web Components with Rails.

Check out the Shoelace Documentation for more information on how to use Shoelace Web Components.

Additional Resources

There is an example repo available to help you get started.

Example Repo: https://github.com/ParamagicDev/rails-shoelace-example

And if you would like to avoid repeating this process, check out the associated Railsbyte for adding Shoelace.

Railsbyte - Shoelace: https://railsbytes.com/templates/X8BsEb

3.4 KiB Raw Blame History