Forem: hersoftsyntax

How to Serve Multiple Themes in Rails Using Sass and esbuild

hersoftsyntax — Sun, 05 Oct 2025 20:49:22 +0000

In this article, I'll show you one way to create multiple themes using a server-side variable that automatically renders a theme in Rails (with esbuild).

What's the use case?

Your page has a parent resource that dictates your app's branding
You don't want spaghetti javascript to handle themes.

Before jumping in, let's understand how the compilation works
Rails has its own default asset pipeline (Sprockets). Its job is to pre-process, concatenate, minify, and serve these files (goes inside public/assets folder). Shifting to esbuild or webpack turns the approach to be more modern (easy to manage dependencies separately from the back-end), faster (written in lower level languages like Go) and flexible (we can configure each step of the process the way we want).

For our approach we will create structure like this:

1 Sass file with all your classes and common imports
1 Sass file with common variables/mixins
1 Sass file per theme with the variables you want to customize
1 method to control the theme to be rendered

Stylesheets

Starting with the common classes and imports, you need to create a partial, meaning, a file starting with an underscore(_). Give it a generic name like styles or global.

// app/assets/stylesheets/_global.scss 
@import "bootstrap/scss/bootstrap";
// your other imports

// your classes
#some-id{
  background: $primary;
}

.some-class {
  background-color: $primary;
}

Then we can create a Sass partial to accommodate common variables which will be needed across all themes.

// app/assets/stylesheets/_common_variables.scss

//
// Color system
//

// GRAY SCALE
$white:  #fff !default;
$gray-100: #d5efd5 !default;
$gray-200: #e9ecef !default;
$gray-300: #dee2e6 !default;
$gray-400: #ced4da !default;
$gray-500: #adb5bd !default;
$gray-600: #85ba91 !default;
$gray-700: #a8dac4 !default;
$gray-800: #343a40 !default;
$gray-900: #212529 !default;
$black:  #000 !default;

// DEFAULT COLORS
$blue:    #0d6efd;
$indigo:  #6610f2;
$purple:  #6f42c1;
$pink:    #d63384;
$red:     #dc3545;
$orange:  #fd7e14;
$yellow:  #ffc107;
$green:   #198754;
$teal:    #20c997;
$cyan:    #0dcaf0;
$light-red: #f6d4d6;

// SYSTEM COLORS
$primary: #0C1439;
$dark: #0C1439;
$secondary:     $gray-600;
$success:       #00B554;
$info:          #5D97D1;
$warning:       #DB7000;
$danger:        #D5113B;
$light:         $gray-100;

$primary-50: #0C143905 !default;
$primary-100: #0C143910 !default;
$primary-200: #0C143920 !default;
$primary-300: #0C143930 !default;
$primary-400: #0C143940 !default;
$primary-500: #0C143950 !default;
$primary-600: #0C143960 !default;
$primary-700: #0C143970 !default;
$primary-800: #0C143980 !default;
$primary-900: #0C143990 !default;

Now, for our theme files, we want to follow a structure like this:

// import common variables

// define theme variables

// import styles

Why do we need to split this way?
All these styles need to be precompiled, meaning when you serve the application your SCSS turns into a single, ready-to-use compiled CSS file (the browser doesn't understand Sass). While I'm using bootstrap for this example, override variables need to be defined before importing it. As well, before our classes. Each theme file will need to have ALL definitions. This might sound redundant, but in reality it just allows the system to serve one single file, instead of all of them, which makes it a bit more performant. Adding to the fact that being precompiled we can't change it dynamically. Any other way would be to create duplicated classes and add a prefix of the theme, but in my opinion that sounds worse. Because you would need to compute for each HTML element what theme you would like to use.

Usually you start your project with an application.scss aggregating all your styles for your app.
In this case, our application will be the default theme to be precompiled.

The default theme:

// app/assets/stylesheets/application.scss
//
// Start Variables
//
@import "common_variables";

$primary: #0C1439;
$dark: #0C1439;
$secondary: $gray-600;
$success: #00B554;
$info: #5D97D1;
$warning:  #DB7000;
$danger:  #D5113B;
$light: $gray-100;

//
// End Variables
//

@import "global";

One theme, let's call it halloween:

// app/assets/stylesheets/halloween.scss

//
// Start Variables
//
@import "common_variables";

$primary: #d5810e;
$dark: #292929;
$secondary: #590606;
$success: #d36546;
$info: #cfc2a1;
$warning: #d3804c;
$danger: #9A0539FF;
$light: #dac3a8;

//
// End Variables
//

@import "global";

Another theme and let's call it xmas:

// app/assets/stylesheets/xmas.scss

//
// Start Variables
//
@import "common_variables";

$primary: #b80606;
$dark: #0d3903;
$secondary: #d3d3d3;
$success: #5da104;
$info: #87b6b6;
$warning: #dd4b2a;
$danger: #700909;
$light: #ffffbe;

//
// End Variables
//

@import "global";

Compilation

This alone doesn't do anything.

When you decide to use Sass in your styles, you will need to compile them into a single .css files, which will be served and read in the browser.

Using esbuild, we need to map each SCSS file to its corresponding compiled CSS file.

You need to make sure you have sass installed in your packages.

// 1
"build:css": "sass ./app/assets/stylesheets/application.scss:./app/assets/builds/application.css ./app/assets/stylesheets/halloween.scss:./app/assets/builds/halloween.css ./app/assets/stylesheets/xmas.scss:./app/assets/builds/xmas.css --no-source-map --load-path=node_modules",

// 2
"build:css:watch": "nodemon --watch ./app/assets/stylesheets/ --ext scss --exec \"yarn build:css\""

Map your scss files into the expected css files
A command (using nodemon, you'll need to add it as well) to watch for changes and compile them

Compile it using yarn build:css.

To see it in action, you can change manually the name of the stylesheet in your main layout, by replacing "application" with "xmas" or "halloween".

<head>
  <!-- ... -->
  <%= stylesheet_link_tag "xmas", "data-turbo-track": "reload" %>
  <!-- ... -->
</head>

If your styles aren't compiling in development, make sure you don't have any 'builds' or 'assets' inside public/. Rails prioritises this folder when you precompile using Rails engine instead of esbuild. You can read more about here it has a small explanation at the end of the section.

Theme selector

Next, we need to automatically swap the theme based on some logic. In this case, I created a resource where I'm expecting a :party parameter and I will use it to determine which theme I want to serve.

# routes.rb
resources :parties, only: [ :show ], param: :party, path: "/"

In our ApplicationController or any other base controller, you need to create a function that looks at this parameter and determines the correct theme.

# application_controller.rb
helper_method :current_theme

# this is not private
def current_theme
  party = params[:party].to_s
  %w[xmas halloween].include?(party) ? party : "application"
end

By using helper_method we're allowing this method to be called from the view.

Basically, we are expecting a parameter that matches the name of one of our stylesheet files; if it doesn't, we'll render our default theme.

Now, we just need to call this function in our main layout application.html.erb, by replacing the string that defines the stylesheet we want to use.

Instead of a url parameter, we could eventually have a button in the UI, save the selection in the session and read from it in the helper_method we just created.

<head>
  <!-- ... -->
  <%= stylesheet_link_tag current_theme, "data-turbo-track": "reload" %>
 <!-- ... -->
</head>

If you look at your Network tab in the browser's inspector, you will see that only one file is downloaded and not all of them.

Happy Coding :)

1 Modal to Rule them All: Rails x Turbo x Stimulus

hersoftsyntax — Sat, 20 Sep 2025 18:23:57 +0000

When implementing modals, it’s common to create them individually in many different places. This can lead to repetitive code cluttering the DOM. One good approach would be to use a strategy similar to flash messages: have just one modal element and use the Hotwire ecosystem(Turbo + Stimulus) to dynamically and reactively change its content.

Dependencies needed

I will be assuming you have everything bellow installed and working as intended.

Gems: rails +8 , turbo-rails +2.0 , stimulus-rails +1.3

Packages: @hotwired/stimulus +3.2 , @hotwired/turbo-rails +8.0 , bootstrap +5.3

Create a modal with dynamic content

Let's just create a simple modal, with a turbo_frame_tag wrapping your body content with a simple bootstrap close button

<!-- views/shared/_modal.html.erb -->
<div class="modal fade">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content d-inline rounded-4">
      <div class="modal-body p-4">
        <div class="position-absolute end-0 px-4">
          <button class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
        </div>
        <%= turbo_frame_tag "modal-body" do %>
        <% end %>
      </div>
    </div>
  </div>
</div>

and render it in your application's layout

<!-- views/layouts/application.html.erb -->
<!-- ... -->
<body>
  <%= render "shared/modal" %>
  <%= yield %>
</body>

Now, in routes, inside your controller you need to add a new route responsible for updating the modal content.

# routes.rb 
resources :modal_test, only: [ :index ] do
  collection do
    get :modal #new endpoint
  end
end

In your controller create the matching method

# controllers/modal_test_controller.rb
class ModalTestController < ApplicationController
  # ...
  def modal
  end
end

Let's create the content for your modal's body

<!-- views/modal_test/_modal_body.html.erb -->
<div>
  Modal Content A
</div>

Then we need a turbo stream file matching the method we just created in our controller, which will be responsible for updating the body content on the turbo frame we added in our _modal.html.erb.

<!-- views/modal_test/modal.turbo_stream.erb -->
<%= turbo_stream.update("modal-body", partial: "modal_test/modal_body") %>

Now you just need to add the button to trigger the modal

<!-- views/modal_test/index.html.erb -->
<div class="container d-flex  flex-column  justify-content-center align-items-center mt-5" >
  <div class="d-flex flex-column justify-content-center align-items-center">
   <%= form_tag(modal_modal_test_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
       <%= button_tag "Modal A", type: :submit, class: "btn btn-primary px-4 py-2" %>
   <% end %>
  </div>
</div>

To make the interaction happen we need to build a stimulus controller. Let's call it modal_controller.js to keep the semantics, and import the necessary classes from stimulusand bootstrap libraries

// app/javascript/controllers/modal_controller.js
import { Controller } from '@hotwired/stimulus';
import { Modal } from 'bootstrap';

export default class extends Controller {

}

Don't forget to add it on the _app/javascript/controllers/index.js_ .

Now let's add our connect function and create our modal object that will be invoking this controller (which we haven't done yet) and add 2 listeners.

turbo:before-stream-render to listen to turbo changes before rendering it

Why **_turbo:before-stream-render_** ?_
We are triggering the modal and the turbo action at the same time, which can lead to race conditions. Without this, you will be opening the modal with empty content before the render happens. The goal here is to open the modal only when the render actually happens. We will be processing turbo stream actions, not navigations, so for instance_
turbo:*-frame-* in the documentation says: "Turbo Frames emit events during their navigation life cycle"_
Listening to the selected event is the only option we have for streams close to when they are triggered._

hidden.bs.modal to look at bootstrap closing modal event

// app/javascript/controllers/modal_controller.js
import { Controller } from '@hotwired/stimulus';
import { Modal } from 'bootstrap';

export default class extends Controller {
    connect() {
        this.modal = new Modal(this.element);

        document.addEventListener('turbo:before-stream-render', /*some function A*/);
        this.element.addEventListener('hidden.bs.modal', /*some function B*/));
    }

    disconnect() {
        document.removeEventListener('turbo:before-stream-render', /*some function A*/));
        this.element.removeEventListener('hidden.bs.modal', /*some function B*/));
    }
}

We need to identify the modal by adding a dynamic ID as a turbo value and initialise it. This will allow us to have multiple modals in the same page and also to execute this code restrictedly for those modals only.

This controller will be instantiated once for each distinct modal rendered on the page. So if you’re including multiple modals with different layouts or IDs, each will have its own instance of the controller. We’ll address this behaviour later in the article.

// app/javascript/controllers/modal_controller.js
export default class extends Controller {
    // new value to store the frameId aka the body id of the modal
    static values = {
        frameId: String,
    }; 

    connect() {
        this.modal = new Modal(this.element);
        // store the reference to the modal
        this.frame = this.hasFrameIdValue ? document.getElementById(this.frameIdValue) : null; 

        document.addEventListener('turbo:before-stream-render', /*some function A*/);
        this.element.addEventListener('hidden.bs.modal', /*some function B*/));
    }
    // ...
}

We can go back to our modal and make sure we call this controller and add the frameId value matching the frame tag from the body as well.

<!-- views/shared/_modal.html.erb -->
<div class="modal fade" id="modal" tabindex="-1" data-controller="modal" data-turbo-permanent data-modal-frame-id-value="modal-body">
 <!-- ... -->
</div>

data-turbo-permanent: this allows the modal to be permanent throughout the pages and ignore turbo navigations — avoiding duplications.

Now we need to build the function that will look at stream changes and toggle the modal via Bootstrap API. And we can also create the function to reset the frame's content once the modal is closed.

// app/javascript/controllers/modal_controller.js
// update connect
document.addEventListener('turbo:before-stream-render', this.toggleModalOnStreamRender.bind(this));
this.element.addEventListener('hidden.bs.modal', this.resetContent.bind(this));

// update disconnect
 document.removeEventListener('turbo:before-stream-render', this.toggleModalOnStreamRender.bind(this));
this.element.removeEventListener('hidden.bs.modal', this.resetContent.bind(this));

// new function
toggleModalOnStreamRender = (event) => {
    // get the target name
    const renderedFrame = event.detail.newStream.target; 
    // check if it maches with the frameId of the modal
    if (renderedFrame !== this.frameIdValue) return;
    this.modal.show();
};

// new function
resetContent = (event) => {
    if (this.frame) this.frame.innerHTML = '';
};

Close modal on submit:turbo action

Modals are typically used to perform an action — such as submitting a form — and are then closed automatically once the controller processes the request. If the form submission leads to a full page refresh, there’s usually no need to handle the modal closing manually. However, in many cases, you may be using Turbo Streams to update part of the page dynamically after the modal submits, in which case you’ll need to explicitly handle closing the modal in your response.

For this approach, we will make the submit action to trigger the turbo event we have been listening in the stimulus controller ( turbo:before-stream-render). Let's add a button inside the body content we want to render in the modal, which will call a new action from our controller.

# routes.rb 
resources :modal_test, only: [ :index ] do
  collection do
    get :modal
    post :modal_action
  end
end

# controllers/modal_test_controller.rb
class ...
  # ...
  def modal_action
    @some_parameter = params[:some_parameter] 
  end
  # ...
end

<!-- views/modal_test/_modal_body.html.erb -->
<div>
  Modal content A
  <%= button_to "Yes",
                modal_action_modal_test_index_url,
                method: :post,
                params: { some_parameter: "some_value_a" },
                class: "btn btn-primary px-4 py-2",
                form_class: "d-inline-block" %>
</div>

Build action for modal submit

Now we will create an isolated turbo stream to trigger the closing behaviour. This segregation allow us to call this close action in any controller responses where we are managing modals.

This action will be responsible for appending a "meta" element which will trigger, again, turbo:before-stream-render event. In this case, we need to add a flag(data-close='true') — by adding a custom attribute to the main element inside of this html. By doing this we can intercept it in our javascript function and react on it to close the modal.

# views/shared/_close_modal.turbo_stream.erb
<%= turbo_stream.append("#{local_assigns[:modal_body_id]}", html: "<span data-close='true'></span>".html_safe) %>

To make it work we need to adapt toggleModalOnStreamRender in our stimulus controller in order to retrieve the custom attribute data-close and whenever it's present we hide the modal.

toggleModalOnStreamRender = (event) => {
    const renderedFrame = event.detail.newStream
    if (renderedFrame.target; !== this.frameIdValue) return;

    // new line here to get the close-action signal
    const isCloseAction = renderedFrame.templateContent.querySelector('[data-close]')?.dataset?.close;

    // close modal if action is present
    if (isCloseAction) this.modal.hide();
    else this.modal.show();
};

Lets add a frame in our index so we can see things changing after submitting the modal.

<!-- views/modal_test/index.html.erb -->
<div class="container d-flex  flex-column  justify-content-center align-items-center mt-5" >
  <div class="d-flex flex-column justify-content-center align-items-center">
   <%= form_tag(modal_modal_test_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
     <%= button_tag "Modal A", type: :submit, class: "btn btn-primary px-4 py-2" %>
   <% end %>
  </div>
  <!-- New frame-->
  <div>
    <h3> Action update: </h3>
    <%= turbo_frame_tag "action-change-modal"  do%>
    <% end %>
  </div>
</div>

Finally, our controller needs to return a Turbo Stream response from the modal_action method (triggered by the button inside the modal). This response should both update the target frame on the page and trigger the modal to close.

# controllers/model_test/modal_action.turbo_stream.erb
<%= turbo_stream.update("action-change-modal", html: "<span> #{@some_parameter}</span>".html_safe) %>
<%= render "shared/close_modal", { modal_body_id: "modal-body" } %>

Multiple places calling the same modal

Let's say that now, you have another use case where a modal is needed. Instead implementing it from scratch, you just need to reuse the same approach, like this:

Create a new partial with the expected content of this new use case

<!-- views/modal_test/_modal_body_b.html.erb -->
<div>
  Modal content B
  <%= button_to "Yes",
                modal_action_modal_test_index_url,
                method: :post,
                params: { some_parameter: "some_value_b" },
                class: "btn btn-primary px-4 py-2",
                form_class: "d-inline-block" %>
</div>

Adapt controller turbo responses or add a new controller method

On the controller side, you can either use the same endpoint if you are on the same page or adding a new route to be called by the turbo-action.

Following the first approach, you can send a value within the buttons identifying which desirable content our controller needs to call to render inside the modal.

<%= form_tag(modal_modal_test_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
  <%= button_tag "Modal A", name: "modal_type", type: :submit, value: "modal_a", class: "btn btn-primary px-4 py-2" %>
  <%= button_tag "Modal B", name: "modal_type", type: :submit, value: "modal_b", class: "btn btn-warning px-4 py-2" %>
<% end %>

# controllers/model_test_controller.rb
class ModalTestController
  # ...
  def modal
    @modal_type = params[:modal_type]
  end
  #...
end

# views/modal_test/modal.turbo_stream.erb
<% modal_type_partial = @modal_type == "modal_a" ? "modal_body_a" : "modal_body_b"  %>
<%= turbo_stream.update("modal-body", partial: "modal_test/#{modal_type_partial}") %>

…or by if inside a new controller (because it might be in a different page)…

<%= form_tag(modal_modal_test_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
   <%= button_tag "Modal A", type: :submit, class: "btn btn-primary px-4 py-2" %>
<% end %>

<%= form_tag(modal_different_controller_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
   # hidden_tag ...
   <%= button_tag "Modal B", type: :submit, class: "btn btn-warning px-4 py-2" %>
<% end %>

# views/modal_test/modal.turbo_stream.erb
<%= turbo_stream.update("modal-body", partial: "modal_test/modal_body_a") %>

# views/different_controller/modal.turbo_stream.erb
<%= turbo_stream.update("modal-body", partial: "modal_test/modal_body_b") %>

# controllers/model_test_controller.rb
class ModalTest
  # ...
  def modal
  end
  #...
end

# controllers/different_controller.rb
class DifferentController
  # ...
  def modal
  end
  #...
end

Add a new modal with a different layout

Let's say now your designer decides to create a different layout that you can't manipulate in your original one. We built the foundation for our modals, so now we just need to recreate a few steps.

Create the baseline of your modal, with a different ID in our frameId matching the same ID as the body

<div class="modal fade" id="different-modal" tabindex="-1" data-controller="modal" data-turbo-permanent data-modal-frame-id-value="modal-different-layout-body">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content d-inline rounded-5">
      <div class="modal-header bg-warning rounded-top-5">
        Title
        <div class="position-absolute end-0 px-4">
          <button class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
        </div>
      </div>
      <div class="modal-body p-4 d-flex flex-column align-items-center">
        This is a modal with a different layout
        <%= turbo_frame_tag "modal-different-layout-body" do %>
        <% end %>
      </div>
    </div>
  </div>
</div>

Render it on the application layout

<body>
  <%= render "shared/modal" %>
  <%= render "shared/modal_different_layout" %>
  <%= yield %>
</body>

Create the body content (in this example we are pointing to the original controller but it could be anything)

<!-- views/modal_test/modal_body_different_layout.html.erb -->
<div>
  Different Layout
  <%= button_to "Yes",
                modal_action_modal_test_index_url,
                method: :post,
                params: { some_parameter: "some_value_different" },
                class: "btn btn-primary px-4 py-2",
                form_class: "d-inline-block" %>
</div>

Add the button to open the new modal

<div class="container d-flex  flex-column  justify-content-center align-items-center mt-5" >
  <div class="d-flex flex-column justify-content-center align-items-center">
    <%= form_tag(modal_modal_test_index_path, method: :get, class: "d-inline-block", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
      <%= button_tag "Modal A", name: "modal_type", type: :submit, value: "modal_a", class: "btn btn-primary px-4 py-2" %>
      <%= button_tag "Modal B", name: "modal_type", type: :submit, value: "modal_b", class: "btn btn-warning px-4 py-2" %>
    <% end %>

     <!-- this step -->
    <%= form_tag(modal_different_layout_modal_test_index_url, method: :get, class: "d-inline-block mt-3", data: { turbo_frame: "modal-body", turbo_stream: true }) do %>
      <%= button_tag "Modal Different Layout", type: :submit, class: "btn btn-danger px-4 py-2" %>
    <% end %>
  </div>

  <div>
    <h3> Action update: </h3>
    <%= turbo_frame_tag "action-change-modal"  do%>
    <% end %>
  </div>
</div>

Create an action on the controller side to render the content of that modal

# controllers/model_test_controller.rb
class ModalTestC
  # ...
  def modal_different_layout
  end
  #...
end

# controllers/modal_different_layout.turbo_stream.rb
<%= turbo_stream.update("modal-different-layout-body", partial: "modal_test/modal_body_different_layout") %>

If you are using turbo actions inside the modal, you just need to call the close_modal partial done previously on this article.

<%= turbo_stream.update("action-change-modal", html: "<span> #{@some_parameter}</span>".html_safe) %>
<%= render "shared/close_modal", { modal_body_id: "modal-body" } %>
<%= render "shared/close_modal", { modal_body_id: "modal-different-layout-body" } %>

Everything together

Sequence diagram

This is just a different way to handle modals, using turbo-streams. There's probably plenty of approaches you can apply accordingly with what suits you better on your use case.

Feel free to share on the comments, what strategies do you apply to handle modals?

Happy coding!