diff --git a/docs/tutorials/integrating-with-rails.md b/docs/tutorials/integrating-with-rails.md index 76f8cc532..ecf1251d2 100644 --- a/docs/tutorials/integrating-with-rails.md +++ b/docs/tutorials/integrating-with-rails.md @@ -10,92 +10,148 @@ This integration has been tested with the following: - Rails >= 6 - Node >= 12.10 -- Webpacker >= 5 +- Yarn >= 1.22 ## Instructions -To get started using Shoelace with Rails, the following packages must be installed. +When using Shoelace, there are mostly three things that need to be served to the client browser: + +- Javascript files for the Web Components +- CSS files for light and dark themes (they can co-exist, but one of them is required) +- Shoelace Icons + +Depending on the JS bundler you are using, you may need to do some additional configuration. However, the basic steps +should be just about the same. Also, it is recommended to read to the [Bundling section in the Installation](/getting-started/installation?id=bundling) +to understand how Shoelace can be set up with a JS bundler in general. In this tutorial, we will assume that your Rails app +is already set up with a JS bundler that supports importing CSS files directly (e.g. Turbopack, esbuild, Vite). + +To get started using Shoelace with Rails, the following package must be installed. ```bash -yarn add @shoelace-style/shoelace copy-webpack-plugin +yarn add @shoelace-style/shoelace ``` -### Importing the Default Theme +This is required regardless of the JS bundler you are using. -The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`. +### Javascript & CSS + +The next step is to import the JavaScript files and default theme for Shoelace. Add the following code to your +entrypoint JS file (generally `application.js`). + +```js +// application.js +import '@shoelace-style/shoelace'; + +// You can also add these two if the JS bundler of your choice supports importing CSS files. +import '@shoelace-style/shoelace/dist/themes/light.css'; +import '@shoelace-style/shoelace/dist/themes/dark.css'; // Optional dark mode +``` + +!> In this example, all Shoelace components are imported for simplicity. However, importing directly from +`@shoelace-style/shoelace` may result in a larger bundle size than necessary. Consider importing only the components +you actually need in the actual application. + +You can also import the CSS inside of a `.css` file if you prefer to maintain a separate CSS entrypoint. +Such as with CssBundling-Rails. ```css -@import '@shoelace-style/shoelace/dist/themes/light'; -@import '@shoelace-style/shoelace/dist/themes/dark'; // Optional dark theme +// application.css +@import '@shoelace-style/shoelace/dist/themes/light.css'; ``` -Fore more details about themes, please refer to [Theme Basics](/getting-started/themes?id=theme-basics). +For more details about themes, please refer to [Theme Basics](/getting-started/themes?id=theme-basics). -### Importing Required Scripts +### Serving up Shoelace Icons -After importing the theme, you'll need to import the JavaScript files for Shoelace. Add the following code to `app/javascript/packs/application.js`. +#### Using the `shoelace-rails` gem -```js -import '../stylesheets/application.scss' -import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@shoelace-style/shoelace' +You do not have to do anything else if you are using [the `shoelace-rails` gem](https://github.com/yuki24/shoelace-rails). +Here are how it works in different environments: -// ... +- In development and test, the icons are served by the `ActionDispatch::Static` middleware, directly from the + `node_modules/@shoelace-style/shoelace/dist/assets/icons` directory. +- In production, the icon files are automatically copied into the `public/assets` directory as part of the + `assets:precompile` rake task. -const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '') +#### Copying Icon files with a Rake task -// Path to the assets folder (should be independent from the current script source path -// to work correctly in different environments) -setBasePath(rootUrl + '/packs/js/') -``` +If you are not using the `shoelace-rails` gem, you can manually copy the icon files to the `public/assets` directory. +One way to do this is to use a rake task and add it as a dependency to the `assets:precompile` task. Most rails +deployment processes run the `rake assets:precompile` task as of part deply, which means that the icon files will be +copied automatically. -### webpack Config +```ruby +# Rakefile +namespace :shoelace do + namespace :icons do + desc "Copy Shoelace icons to the assets path" + task copy: :environment do + cp_r "node_modules/@shoelace-style/shoelace/dist/assets", Rails.public_path + end + end +end -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. - -```js -const { environment } = require('@rails/webpacker'); - -// Shoelace config -const path = require('path'); -const CopyPlugin = require('copy-webpack-plugin'); - -// Add shoelace assets to webpack's build process -environment.plugins.append( - 'CopyPlugin', - new CopyPlugin({ - patterns: [ - { - from: path.resolve(__dirname, '../../node_modules/@shoelace-style/shoelace/dist/assets'), - to: path.resolve(__dirname, '../../public/packs/js/assets') - } - ] - }) -); - -module.exports = environment; -``` - -### Adding Pack Tags - -The final step is to add the corresponding `pack_tags` to the page. You should have the following `tags` in the `` section of `app/views/layouts/application.html.erb`. - -```html - - - - - - <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> <%= javascript_pack_tag - 'application', 'data-turbolinks-track': 'reload' %> - - - <%= yield %> - - +Rake::Task["assets:precompile"].enhance(["shoelace:icons:copy"]) ``` Now you can start using Shoelace components with Rails! +## Using Rails View Helpers + +[the `shoelace-rails` gem](https://github.com/yuki24/shoelace-rails) is a community-maintained library that provides useful Rake tasks and Rails view helpers for +Shoelace components. In order to use it, add the gem by running the following command: + +```bash +bundle add shoelace-rails +``` + +Once it is installed, you should be able to use the following view helpers to render Shoelace components: + +```erb +<%= sl_form_for @user do |form| %> + <% # Text input: https://shoelace.style/components/input %> + <%= form.text_field :name %> + <%= form.password_field :password, placeholder: "Password Toggle", 'toggle-password': true %> + + <% # Radio buttons: https://shoelace.style/components/color-picker %> + <%= form.color_field :color %> + + <% # Radio buttons: https://shoelace.style/components/radio %> + <%= form.collection_radio_buttons :status, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last %> + + <% # Select: https://shoelace.style/components/select %> + <%= form.collection_select :tag, { id_1: "Option 1", id_2: "Option 2", id_3: "Option 3" }, :first, :last, {}, { placeholder: "Select one" } %> + + <%= form.submit %> +<% end %> +``` + +And this code will produce: + +```html +
+ + + + + + Option 1 + Option 2 + Option 3 + + + + Option 1 + Option 2 + Option 3 + + + Create User +
+``` + +For more details about the gem, please refer to [the official README](https://github.com/yuki24/shoelace-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.