2020-10-08 12:55:50 +00:00
# Integrating with Rails
2021-11-16 14:19:34 +00:00
This page explains how to integrate Shoelace with a Rails app.
?> This is a community-maintained document. Please [ask the community ](/resources/community ) if you have questions about this integration. You can also [suggest improvements ](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-rails.md ) to make it better.
2020-10-08 12:55:50 +00:00
## Requirements
This integration has been tested with the following:
- Rails >= 6
- Node >= 12.10
- Webpacker >= 5
## Instructions
To get started using Shoelace with Rails, the following packages must be installed.
```bash
yarn add @shoelace -style/shoelace copy-webpack-plugin
```
### Importing the Default Theme
The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss` .
```css
2021-10-11 12:25:09 +00:00
@import '~@shoelace-style/shoelace/dist/themes/light';
@import '~@shoelace-style/shoelace/dist/themes/dark'; // Optional dark theme
2020-10-08 12:55:50 +00:00
```
2021-10-11 12:25:09 +00:00
Fore more details about themes, please refer to [Theme Basics ](/getting-started/themes?id=theme-basics ).
2020-10-08 12:55:50 +00:00
### Importing Required Scripts
After importing the theme, you'll need to import the JavaScript files for Shoelace. Add the following code to `app/javascript/packs/application.js` .
```js
import '../stylesheets/application.scss'
2021-02-26 14:09:13 +00:00
import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@shoelace-style/shoelace'
2020-10-08 12:55:50 +00:00
// ...
2020-12-12 16:21:36 +00:00
const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '')
2021-02-26 14:09:13 +00:00
// Path to the assets folder (should be independent from the current script source path
2020-12-12 16:21:36 +00:00
// to work correctly in different environments)
2021-02-26 14:09:13 +00:00
setBasePath(rootUrl + '/packs/js/')
2020-10-08 12:55:50 +00:00
```
### webpack Config
2021-02-26 14:09:13 +00:00
Next we need to add Shoelace's assets to the final build output. To do this, modify `config/webpack/environment.js` to look like this.
2020-10-08 12:55:50 +00:00
```js
const { environment } = require('@rails/webpacker')
// Shoelace config
const path = require('path')
const CopyPlugin = require('copy-webpack-plugin')
2021-02-26 14:09:13 +00:00
// Add shoelace assets to webpack's build process
2020-10-08 12:55:50 +00:00
environment.plugins.append(
'CopyPlugin',
new CopyPlugin({
patterns: [
{
from: path.resolve(
__dirname,
2021-02-26 14:09:13 +00:00
'../../node_modules/@shoelace-style/shoelace/dist/assets'
2020-10-08 12:55:50 +00:00
),
2021-02-26 14:09:13 +00:00
to: path.resolve(__dirname, '../../public/packs/js/assets')
2020-10-08 12:55:50 +00:00
}
]
})
)
2020-11-05 13:14:25 +00:00
module.exports = environment
2020-10-08 12:55:50 +00:00
```
### Adding Pack Tags
The final step is to add the corresponding `pack_tags` to the page. You should have the following `tags` in the `<head>` section of `app/views/layouts/application.html.erb` .
```html
<!DOCTYPE html>
< html >
< head >
<!-- ... -->
< %= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
< %= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
< / head >
< body > < %= yield %>< / body >
< / html >
```
Now you can start using Shoelace components with Rails!
## Additional Resources
- There is a third-party [example repo ](https://github.com/ParamagicDev/rails-shoelace-example ), courtesy of [ParamagicDev ](https://github.com/ParamagicDev ) available to help you get started.
- If you would like to avoid repeating this process, check out the associated [Railsbyte for Shoelace ](https://railsbytes.com/templates/X8BsEb ).