mirror
/
shoelace
kopia lustrzana https://github.com/shoelace-style/shoelace
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność
shoelace/docs/tutorials/integrating-with-rails.md

104 wiersze
3.1 KiB
Markdown
Czysty Zwykły widok Historia

Add integrating with rails to tutorials section
2020-10-08 12:55:50 +00:00
# Integrating with Rails
This page explains how to integrate Shoelace with a Rails app. This is a community-maintained document. For questions about this integration, please [ask the community](https://discord.gg/mg8f26C).
## 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
@import '~@shoelace-style/shoelace/dist/shoelace/shoelace';
```
### 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'
import { defineCustomElements, setAssetPath } from '@shoelace-style/shoelace'
// ...
Fix asset path for Rails (#268) The path to assets should be consistent and not depend on the current script source. There are at least two situations when this assumption fails: - When running `webpacker-dev-server`, the _pack_ URL doesn't contain `/js/` part. - In test environment, `/packs-test` is used by default.
2020-12-12 16:21:36 +00:00
const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '')
// Path to the assets folder (should be independent on the current script source path
// to work correctly in different environments)
setAssetPath(rootUrl + '/packs/js/')
Add integrating with rails to tutorials section
2020-10-08 12:55:50 +00:00
// This enables all web components for the current page
defineCustomElements()
```
?> This will import all Shoelace components for convenience. To selectively import components, refer to the [Using webpack](/getting-started/installation?id=using-webpack) section of the docs.
### webpack Config
Next we need to add Shoelace's icons to the final build output. To do this, modify `config/webpack/environment.js` to look like this.
```js
const { environment } = require('@rails/webpacker')
// Shoelace config
const path = require('path')
const CopyPlugin = require('copy-webpack-plugin')
// Add 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')
}
]
})
)
Fix Rails Integration docs: Missing module export statement (#263) Thanks for this great library @claviska! Tried adding Shoelace to a Rails app w/ the current guide. When starting the Webpack Dev Server, the following error gets thrown: ``` .../RailsApplication/config/webpack/development.js:5 module.exports = environment.toWebpackConfig() ``` Adding `module.exports = environment` as done [here in the example repo](https://github.com/ParamagicDev/rails-shoelace-example/blob/4114da0e14e7276718df5091f28be7a96513144b/config/webpack/environment.js#L20) fixes the issue and allows Webpack to compile.
2020-11-05 13:14:25 +00:00
module.exports = environment
Add integrating with rails to tutorials section
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).