DEV Community: Rails Designer

Perron 1.0 here is here

Rails Designer — Thu, 30 Apr 2026 16:30:00 +0000

Nine months ago, I introduced Perron, an OSS Rails-based static site generator. 190 commits and 18 releases later, lots of bugfixes and many new features—by yours truly and a few others—have been added. Today I am thrilled to announce Perron 1.0. 🥳

Want to check it out right away? Check out the docs, star it on GitHub or explore the showcase to see what others have built. 😻

Programmatic SEO

One of the most exciting features has been the ability to generate content programmatically. Whether you are building a SaaS directory, product comparison pages or anything else that mixes data with thousands of pages, with Perron this is now super easy.

Learn more about programmatic content creation.

Pull content using third-party APIs

Your content does not have to live in markdown files or data files. Building on top of the same sources feature that powers Perron’s programmatic feature, you can now pull content from third-party APIs. Great to pull content from CMS’, pull data from your GitHub account or whatever else that has an API.

Preview draft or scheduled content

This is one of those features that arrived from a personal pain: how to share a scheduled or draft article with others? Just set preview: true in the resource’s frontmatter and share the private link. Read all about it.

Live reload

Development just got faster. 🏎️💨 Perron live reloads using DOM morphing through the mata gem. It is a framework-agnostic gem I built specifically for Perron, but can be used with any Ruby framework. Watch your changes appear instantly in the browser without a full page refresh. Will announce this gem properly later. 🤫

But wait… there is more! 🤩

Processors to transform markdown; add target=_blank to links, transform images’ paths to be absolute or create your own processors to transform HTML however you need
Query your resources like Rails; use familiar methods like where, order and scope
Work directly with data sources; use data from CSV, JSON and YAML files
has_many and belongs_to; familiar class methods from Rails to associate resources with each other
Feeds out of the box; RSS, JSON and Atom feeds are now included out-of-the-box
Markdown support; whether you prefer kramdown, redcarpet or commonmarker, Perron works with all of them
Display related resources; show related posts, products or any other resources on your pages
Navigate with previous and next; built-in methods to navigate through your resources in sequence

Library additions

The library continues to grow with new snippets, components and templates:

Full text search form; add full text search to your site (also used on the docs site)
Filter elements; let your visitors filter content by category, tag or any other attribute
Embed content; useful for embedding a changelog or other content from your Perron site into your app
LLM skill; make sure your LLM agent knows its way around Perron
Documentation template; the template that also powers the Perron docs

What’s next?

Perron 1.0 is stable and ready for production (like this very site! 💡). But this is just the beginning. The showcase is growing with sites built by the community and there is plenty more to come. 🚀🌕

A huge thank you to @ianyamey, @goose3228 and @m-lague for their contributions and feedback along the way. ❤️

If you have not tried Perron yet, now is the time to hop on. Check out the docs, explore the library and star the repo. Would love to see what you will build. 🚂

Catch JavaScript errors with user-friendly error feedback

Rails Designer — Thu, 23 Apr 2026 16:30:00 +0000

JavaScript errors (either vanilla or with Stimulus controllers) often happen silently in the browser, leaving your users confused about what went wrong. “Why did nothing happen?”. “I just did click the button!” “Let’s try again…”. Still nothing… Starts furiously clicking the button now.

This poor user experience can be frustrating and can lead to more support tickets that could have been prevented. In this article I want to show how to build a simple class that catches unhandled JavaScript errors and displays them to the user in a friendly banner. It’s a small but meaningful improvement to your app’s user experience.

As always, the code can be found on GitHub.

The silence of the errors

When a JavaScript error occurs and isn’t caught, it silently fails in the background. The user has no idea what happened. You as a developer might inspect the browser’s console, but you are not a normie. Did the request fail? Is the app broken? Should they refresh the page? Without feedback, they’re left guessing.

A simple error banner at the top of the page can help with this. It tells the user something went wrong and gives them the option to dismiss it or take action.

Hello noisy errors

The ErrorFeedback class is straightforward. It listens for unhandled errors and promise rejections, then displays them in a banner:

// app/javascript/error_feedback.js
export default class ErrorFeedback {
  #banner = null
  _timeout = null

  constructor(options = {}) {
    this.duration = options.duration ?? 5000
    this.message = options.message ?? "Something went wrong. Please try again."
    this.visibleClass = options.visibleClass ?? "is-visible"

    this.#setup()
  }

  static gottaCatchThemAll(options) {
    return new this(options)
  }

  #setup() {
    window.onerror = (msg, src, line, col, error) => {
      this.#show(msg || error?.message)

      return true
    }

    window.onunhandledrejection = (event) => {
      this.#show(event.reason?.message || event.reason)
    }
  }

  #show(text) {
    if (!this.#banner) this.#createBanner()

    this.#banner.querySelector("p").textContent = text || this.message
    this.#banner.classList.add(this.visibleClass)
    this.#scheduleDismiss()
  }

  #hide = () => {
    if (this.#banner) this.#banner.classList.remove(this.visibleClass)

    this.#clearSchedule()
  }

  #createBanner() {
    this.#banner = document.createElement("div")
    this.#banner.className = "error-feedback"
    this.#banner.innerHTML = `
      <p></p>

      <button type="button" aria-label="Dismiss">×</button>
    `
    this.#banner.querySelector("button").addEventListener("click", this.#hide)

    document.body.appendChild(this.#banner)
  }

  #scheduleDismiss() {
    this.#clearSchedule()

    if (this.duration > 0) this._timeout = setTimeout(this.#hide, this.duration)
  }

  #clearSchedule() {
    if (this._timeout) {
      clearTimeout(this._timeout)

      this._timeout = null
    }
  }
}

[!tip]

If above class is overwhelming to you, why not check out JavaScript for Rails Developers? It touches upon many of the syntax you see above.

The class catches two types of errors: synchronous errors via window.onerror and promise rejections via window.onunhandledrejection. When an error occurs, it extracts the error message and displays it in the banner.

The banner automatically dismisses after a (configurable) 5 seconds.

Enable the banner

Initialize the error feedback in your main application file:

// app/javascript/application.js
import "@hotwired/turbo-rails"
import "controllers"
import ErrorFeedback from "errors"

ErrorFeedback.gottaCatchThemAll() // I am too old to fully get this reference, but I think it is accurate enough

And that is it! The class is now listening for errors across your entire app.

Where to go from here

The banner can be easily extended with additional features. You could add a link to your documentation, a button to contact support or even integrate with error monitoring tools like Appsignal or Honeybadger.

For example, you could add a link to your support chat:

this.#banner.innerHTML = `
  <p></p>

  <div>
    <a href="https://example.com/chat">Chat with support</a>

    <button type="button" aria-label="Dismiss">×</button>
  </div>

Or extend the class to send errors to an external service:

#show(text) {
  if (!this.#banner) this.#createBanner()

  this.#banner.querySelector("p").textContent = text || this.message
  this.#banner.classList.add(this.visibleClass)
  this.#scheduleDismiss()

  // Send to error monitoring service
  this.#reportError(text)
}

#reportError(message) {
  // Send to Appsignal, Honeybadger, etc.
}

This simple class is not a replacement for proper error monitoring tools. Those tools provide detailed stack traces, user session replay and analytics that are super useful for debugging sessions. But this banner fills an important gap: it gives your users immediate feedback when something goes wrong, improving their experience and reducing confusion.

Level up CSS transitions with cubic-bezier

Rails Designer — Thu, 16 Apr 2026 19:15:00 +0000

This article was originally published on Rails Designer

If you've ever noticed that your CSS transitions feel a bit… flat, you're not alone (I seem them a lot! 😭). The default ease timing function works fine, but it's generic. Real-world motion has character, it bounces, overshoots and feels natural. That is what cubic-bezier is for.

What is cubic-bezier?

In CSS, cubic-bezier is used in the transition-timing-function or animation-timing-function property. It defines how intermediate values are calculated during a transition using a cubic Bézier curve (orly?! 🦉).

The syntax looks like this:

cubic-bezier(x1, y1, x2, y2)

Those four numbers define two control points on a curve. The curve starts at (0,0) and ends at (1,1), representing the beginning and end of the transition. The control points shape how the animation progresses between those states.

For a detailed explanation, check out the MDN Web Docs.

Examples that make a difference

Let's look at some examples that use default easing functions and then show a more interesting timing functions. Hover to see the effects:

(Please see the original article for live before/after examples)

This is how it is done with Tailwind CSS:

<div class="transition duration-500 ease-[cubic-bezier(0.68,-0.6,0.32,1.6)] hover:scale-80 hover:rotate-359"></div>

And how you write it with CSS:

.icon {
  transition: transform 0.5s cubic-bezier(.68 -.6 .32 1.6);
}
.icon:hover {
  transform: scale(0.8) rotate(359deg);
}

(Please see the original article for live before/after examples)

This is how it is done with Tailwind CSS:

<div class="transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] hover:scale-150"></div>

And how you write it with CSS:

.button {
  transition: transform 0.3s cubic-bezier(.34 1.56 .64 1);
}
.button:hover {
  transform: scale(1.5);
}

(Please see the original article for live before/after examples)

This is how it is done with Tailwind CSS:

<div class="transition-transform duration-500 ease-[cubic-bezier(0.87,0,0.13,1)] hover:translate-x-8"></div>

And how you write it with CSS:

.pill {
  transition: transform 0.5s cubic-bezier(.87 0 .13 1);
}
.pill:hover {
  transform: translateX(2rem);
}

Notice the negative values in the cubic-bezier functions? Those create the "bounce" effect that overshoots its target before settling into place and what gives that "premium" feel.

[!note]
Tailwind CSS provides better defaults with ease-{in,out,in-out} classes

Finding the perfect curve

Rather than guessing values, use Easing Wizard. It's a beautiful, interactive tool (that I shared in my notes some weeks ago; only accessible via atom feed 🤫) where you can drag control points and see the resulting animation in real-time. Copy the generated cubic-bezier values directly into your CSS.

The difference between ease and a well-crafted cubic-bezier curve is immediately noticeable. Your interfaces will feel more responsive, more alive and more professional.

Try replacing your next transition: all 300s ease with transition: all 300s cubic-bezier(.68 -.6 .32 1.6) and see the difference for yourself.

Announcing Fuik: a webhook engine for Rails

Rails Designer — Fri, 10 Apr 2026 16:30:00 +0000

Webhooks are one of those super simple but really powerful tools that almost every developer has needed to use at least once. From Stripe, GitHub to Postmark. Setting up webhooks is not difficult, but there is quite a bit of boilerplate involved: payload storage, event routing and signature verification. Repetitive. Tedious. Boring. Oh, and did I mention debugging?

Meet Fuik : a Rails engine that catches and stores webhooks from any provider, then gives you a clean way to process them.

👉 If you want to check out the repo and star ⭐ it, that would make my day! 😊

You can install Fuik simply by running bundle add fuik and then run the install generator and migrate the database. Seconds of work! Your app can now receive webhooks at /webhooks.

Then visit /webhooks to view all received webhooks. Click any event to see the full payload (that’s where Fuik has some powereful features stored for you; more on that below).

But just looking at your webhook payloads is not enough. Fuik maps every event with a dedicated class. Create one by running:

bin/rails generate fuik:provider stripe checkout_completed

This creates app/webhooks/stripe/checkout_session_completed.rb. Add your business logic:

module Stripe
  class CheckoutSessionCompleted < Base
    def process!
      User.find_by(id: payload.client_reference_id).tap do |user|
        user.activate_subscription!
        user.send_welcome_email
      end

      @webhook_event.processed!
    end
  end
end

Fuik’s UI has quite a few more trick up its sleeve to help you (or your LLM friend) debug your webhook issues. 🤖⚡

Copy payload as JSON : click a button, payload is in your clipboard
Download payload as JSON file : keep it for testing, debugging or throw it at your LLM agent, bot or colleague.
Add .json to any URL : get the raw payload without the UI
Click any key to get the Ruby accessor path : click product_id (as seen in the above screenshot) in the dashboard and get payload["line_items"][0]["product_id"] (say what? 🤯)

Fuik includes templates for a small selection of providers I needed. Built one yourself? Upstream it and submit a PR. Help your fellow developer by contributing to OSS. ❤️

Already using Fuik? Star it on GitHub. ⭐

Form Objects vs Service Objects in Rails

Rails Designer — Thu, 09 Apr 2026 05:30:00 +0000

When building a SaaS with Rails, I often have more complex logic that spans multiple models and actions. Over time, I’ve settled on two distinct patterns: Form Objects and what I’ll just call classes (or POROs). They serve different purposes, and knowing when to reach for each has made my code easier to reason about and test.

Let me walk you through how I use them both.

Use Form Objects for user input

I use Form Objects when I have a form that a user interacts with directly, and that form needs to create (or update) more than one record. The key is the direct mapping to the form itself.

A Form Object should “quack” like an Active Record model. It validates input, it responds to #save, and it works seamlessly with Rails’ form helpers. Here’s an example:

# app/models/signup.rb
class Signup < ApplicationForm
  attribute :name, :string
  attribute :email_address, :string
  attribute :password, :string
  attribute :terms, :boolean, default: false
  attribute :receive_product_updates, :boolean, default: false

  normalizes :email_address, with: -> { it.strip.downcase }

  validates :name, :email_address, :password, presence: true
  validates_format_of :email_address, with: URI::MailTo::EMAIL_REGEXP
  validates :password, length: 8..128
  validates :terms, acceptance: { message: "and privacy policy need to be accepted" }

  def save
    if valid?
      transaction do
        @user = create_user.tap { it.setup_workspace(member_name: name).save }.tap do |user|
          user.create_preferences.tap do |preferences|
            preferences.update receive_product_updates: receive_product_updates
          end

          send_welcome_email_to user
        end
      end
    end
  end

  attr_reader :user

  private

  def create_user = User.create!(email_address: email_address, password: password)

  def send_welcome_email_to(user) = WelcomeEmailJob.perform_later user.email_address
end

See the inherited ApplicationForm? That is what makes most of the “quacking” possible (iirc, I got this approach from the Layered Rails Design book):

class ApplicationForm
  include ActiveModel::Model
  include ActiveModel::Attributes
  include ActiveModel::Attributes::Normalization
  include ActiveModel::Validations::Callbacks

  def model_name
    ActiveModel::Name.new(self, nil, self.class.name.sub(/Form$/, ""))
  end

  def transaction(&block) = ActiveRecord::Base.transaction(&block)
end

In the controller, it works just like you’d expect:

class SignupsController < ApplicationController
  def new
    @signup = Signup.new
  end

  def create
    @signup = Signup.new(signup_params)

    if user = @signup.save
      start_new_session_for user
      redirect_to root_url
    else
      redirect_to new_signups_path
    end
  end

  private

  def signup_params; end
end

The Form Object has all the logic needed to handle the signup flow. Validations, record creation, side effects live in one place that mirrors the form itself.

For everything else use POROs

For logic that isn’t tied to a specific form, I just write a regular class. I avoid the term “Service Object” and the suffix “Service” altogether (personally hate the term!). Instead, I name it after what it actually does and I like to namespace them if related to another class (or ActiveRecord model).

Consider inviting a user to a workspace. This isn’t a form submission; it’s an action triggered programmatically (but it could be called from a form object). Here’s how I’d handle it:

# app/models/member/setup.rb
class Member::Setup
  def initialize(workspace:, user:, role: "member", name: "Unknown")
    @workspace = workspace
    @user = user
    @role = role&.to_sym
    @name = name
  end

  def save
    ActiveRecord::Base.transaction do
      create_member.tap do |member|
        add_roles_to member
        mark_workspace_current
        create_profile_for member
      end
    end
  end

  private

  def create_member = Member.create(workspace: @workspace, user: @user)

  def add_roles_to(member)
    roles.each do |role_name|
      member.actors.create role: Role.where(name: role_name).first_or_create
    end
  end

  def mark_workspace_current = @user.update!(workspace: @workspace)

  def create_profile_for(member) = member.create_profile(name: @name)

  def roles
    {
      administrator: %w[administrator],
      member: %w[member],
      owner: %w[administrator billing member owner]
    }[@role] || []
  end
end

Notice the naming: Member::Setup. No “Service” suffix, just the thing it does, namespaced under the model it primarily concerns.

This class isn’t invoked directly. Instead, I add a method to the Workspace model:

class Workspace < ApplicationRecord
  has_many :members, dependent: :destroy

  def add_member(to:, role: nil, name: nil)
    Member::Setup.new(workspace: self, user: to, role: role, name: name).save
  end
end

Now the API is clean and expressive:

workspace.add_member User.first
workspace.add_member User.find(2), role: "administrator", name: "Alice"

One place to rule them all

I keep everything in app/models. No app/services folder and or app/forms. This keeps my project structure flat and makes it obvious that these are domain logic, not infrastructure.

Here is a simple table to summarize this, already short, article. 😅

Aspect	Form objects	POROs
When	Direct response to user input via a form	Business logic not tied to a form
Naming	Match the form (`Signup`, `ProjectInvite`)	What it does (`Member::Setup`, `Invoice::Generate`)
Return value	Always responds to `#save`; typically returns an AR model	Depends on use case; could be an object or `true`/`false`
Invocation	Directly from controller	From other classes or model methods
Location	`app/models/`	`app/models/`, namespaced as needed

This approach gives me clarity about what each class does and when to reach for it. It is just enough organisation. Form Objects handle forms and their side effects. Classes handle everything else. Both live where they belong, named clearly and no ugly suffixes required.

Refactoring a JavaScript class

Rails Designer — Thu, 02 Apr 2026 18:15:00 +0000

This article was originally published on Rails Designer

This article is taken from the book JavaScript for Rails Developers (use ONE-YEAR-OLD to get 25% discount 🥳). It is a book I published about a year ago. Over that period, many hundreds bought the book. It is written for Ruby/Rails developers to make JavaScript your 2nd favourite language.

I always get a little excited when I see a good refactoring happen. So I want to share this article; it is one of the last chapters where I go over an exisintg part of the code that is created in the book to refactor it with the goal to make it:

more readable;
easier to understand at a glance.

This is the current code it started with:

import { Annotation, Transaction } from "@codemirror/state"
import { EditorView } from "codemirror"

const editorCache = {
  pairs: new WeakMap(),
  store(sourceEditor, duplicateEditor) {
    this.pairs.set(sourceEditor, duplicateEditor)
  },

  get(editor) {
    return this.pairs.get(editor)
  }
}

export const splitView = {
  for: (editor, { enabled }) => {
    if (!enabled) return

    const syncAnnotation = Annotation.define()
    const sync = (transaction, sourceEditor) => {
      const documentLengthMismatch = transaction.changes && transaction.changes.length !== sourceEditor.state.doc.length

      if (documentLengthMismatch) return

      sourceEditor.update([transaction])

      const hasContentChanges = !transaction.changes.empty
      const isUserChange = !transaction.annotation(syncAnnotation)

      if (hasContentChanges && isUserChange) {
        const targetEditor = editorCache.get(sourceEditor)

        if (!targetEditor) return

        const annotations = [
          syncAnnotation.of(true),
          transaction.annotation(Transaction.userEvent)
        ].filter(Boolean)

        targetEditor.dispatch({
          changes: transaction.changes,
          annotations
        })
      }
    }

    const newEditor = new EditorView({
      state: editor.state,
      parent: editor.dom.parentElement,
      dispatch: transaction => sync(transaction, newEditor)
    })

    const duplicateEditor = new EditorView({
      state: newEditor.state,
      parent: editor.dom.parentElement,
      dispatch: transaction => sync(transaction, duplicateEditor)
    })

    editorCache.store(newEditor, duplicateEditor)
    editorCache.store(duplicateEditor, newEditor)

    editor.destroy()

    return duplicateEditor
  },

  destroy: (editor) => {
    editor?.destroy()
  }
}

It takes a lot brainpower to understand or just scan what is happening and how things flow. I can see a named export for splitView that has two methods: for and destroy. And only destroy is instantly clear to me. That whole for method takes some serious computing time. By the time, a few weeks later, you need to make changes again to this file (or someone else from your team), you already have forgotten what the flow of the code was.

So here is my proposed, refactored class. Below it I will highlight some of the details.

import { Annotation, Transaction } from "@codemirror/state"
import { EditorView } from "codemirror"

class SplitViewClass {
  create(editor, enabled) {
    if (!enabled) return

    const firstEditor = this.#createClone({ from: editor })
    const secondEditor = this.#createClone({ from: editor })

    this.#pair(firstEditor, { with: secondEditor })

    editor.destroy()

    return secondEditor
  }

  // private

  #pairs = new WeakMap()
  #syncAnnotation = Annotation.define()

  #createClone({ from: sourceEditor }) {
    return new EditorView({
      state: sourceEditor.state,
      parent: sourceEditor.dom.parentElement,
      dispatch: (transaction, editor) => this.#sync(transaction, { to: editor })
    })
  }

  #pair(firstEditor, { with: secondEditor }) {
    this.#pairs.set(firstEditor, secondEditor)
    this.#pairs.set(secondEditor, firstEditor)
  }

  #sync(transaction, { to: firstEditor }) {
    if (this.#cannotSync(transaction, { to: firstEditor })) return

    firstEditor.update([transaction])

    if (!transaction.changes.empty && !transaction.annotation(this.#syncAnnotation)) {
      const secondEditor = this.#pairs.get(firstEditor)

      if (!secondEditor) return

      secondEditor.dispatch({
        changes: transaction.changes,
        annotations: this.#createAnnotations({ from: transaction })
      })
    }
  }

  #cannotSync(transaction, { to: firstEditor }) {
        return transaction.changes?.length !== firstEditor.state.doc.length
  }

  #createAnnotations({ from: transaction }) {
    return [
      this.#syncAnnotation.of(true),
      transaction.annotation(Transaction.userEvent)
    ].filter(Boolean)
  }
}

export const splitView = {
  for: (editor, { enabled }) => new SplitViewClass().create(editor, { enabled }),
  destroy: (editor) => editor?.destroy()
}

In terms of lines of code, they are very much the same (70 vs 71; refactored is longer!). But I argue the refactored version is way easier to grasp. Just one public method, create, that is readable.

create(editor, enabled) {
  if (!enabled) return

  const firstEditor = this.#createClone({ from: editor })
  const secondEditor = this.#createClone({ from: editor })

  this.#pair(firstEditor, { with: secondEditor })

  editor.destroy()

  return secondEditor
}

It is actual readable: return when not enabled. Then create one cloned editor from the (given) editor, then another one stored as secondEditor. Then pair the first editor with the second editor.

From here you can follow the code as as you need more details as the methods are ordered by level of abstraction: createClone, pair. And then methods invoked from there. Using named parameters like { from: ... } and { with: ... } really helps with making the intent clear.

Look at this early return:

if (this.#cannotSync(transaction, { to: firstEditor })) return

Chef's kiss, am I right?

Also small, focused methods that don't give you a headache! Each method does one thing, uses early returns for clarity so no complex conditionals. And what's more, as done earlier in chapter 8.2, the API stays the same. So to use this class with the bundled resource, simply replace: import { splitView } from "./editor/splitView" with import { splitView } from "./editor/splitViewClass".

destroy just calls the editor's built-in destroy() method (using optional chaining ?. (as covered in an earlier chapter) in case the editor is undefined), without needing to handle any cleanup of our pairs since the WeakMap automatically handles that when editors are garbage collected.

Everyone, say “hi” again to Rails Icons 👋

Rails Designer — Thu, 26 Mar 2026 07:30:00 +0000

Late 2024 I published Rails Icons 1.0 (slighly off-topic, but I mentioned a modest few thousand downloads in that article; now it is close to 250k; I expect the same + a bit more for Perron). Today I like to re-introduce Rails Icons again to you: here is version 1.8.

(I did not expect SVG icons could be this exciting; and I have a few more ideas still! 🤯)

First I extracted the sync and SVG creation logic (the bit people have copy-pasted instead of using/contributing to the gem) into its own gem: Icons, I wrote about it here. The main goal was to make the “behind-the-scenes” architecture (syncing, normalizing icon names, etc.) available for others to build a similar gem for their framework of choice like Hanami, Roda and so on. That logic is novel and could be used in any kind of Ruby app. This keeps the Rails Icons even more light-weight and allows me to add features I want to share with you today.

Like (experimental) support for Ruby LSP.

This allows you to write icon "|" in your IDE and it will show a completion dialog for all synced icon names. This works also with variant and library name. It is still early stage and would love some help from you if you are experienced with Ruby LSP. 🙏

Then a feature I have had on my list for well over a year: a preview of all your icons 😻

Simply add mount RailsIcons::Engine => "rails_cons" to your routes and you are presented with this lovely view:

Here you can:

search by icon name and by related keyword (added small mappings for all Rails Icons’ supported libraries, hence you can search for nature, vehicle and travel 😊)
copy name
copy helper (so for above screenshot it copies: icon('bulldozer'), and it will add the variant if that one is not your configured default variant 💡)
query is stored in url so it shareable with your team (of LLM bots 😭)

I think this is pretty cool! 😎

I thought these ~~two~~ three big features were well worth a re-introduction. If you haven’t checked it out, it is here on GitHub. Be sure to star ⭐ it! ✌️

If you are already using Rails Icons, be sure to add your project to the list. Downloads and stars are nice and all for the larger community, usage in real projects are a true motivator for the maintainer (i.e. me).

Build custom emojis with Stimulus

Rails Designer — Thu, 19 Mar 2026 17:15:00 +0000

This article was originally published on Rails Designer Blog

Recently I had to build something using the canvas element. Today I'll show you how to build an interactive emoji composer using HTML Canvas and Stimulus. Click emojis to add them to a canvas, drag them around and export your creation as an image. It is quite fun (coming from an emoji connoisseur)! 😎👍

Click a face emoji, add some accessories, position everything just right and download your custom creation. All running in the browser with no external dependencies.

View the full code on GitHub

The HTML

Start with a simple layout that divides the screen into a canvas area and emoji picker:

<div data-controller="canvas-composer image-exporter">
  <div class="grid grid-cols-[1fr_clamp(240px,12%,480px)] gap-8">
    <div>
      <canvas
        data-canvas-composer-target="canvas"
        width="300"
        height="300"
        data-action="mousedown->canvas-composer#selectEmoji mousemove->canvas-composer#moveSelectedEmoji mouseup->canvas-composer#deselectEmoji">
      </canvas>

      <div class="grid grid-cols-2 mt-2 gap-x-3">
        <button data-action="click->canvas-composer#clearAll">
          Clear canvas
        </button>

        <button data-action="click->image-exporter#download">
          Save as image
        </button>
      </div>
    </div>

    <div class="grid grid-cols-2 gap-6">
      <ul class="grid grid-cols-2 gap-1">
        <%%= render partial: "button", collection: %w[😀 😊 😠 😮 😳 😉 😟 😐 🥺 🙄 👶 👦 👧 🧑 👨 👩 🧓 👴 👵 🤖], as: :emoji %>
      </ul>

      <ul class="grid grid-cols-2 gap-1">
        <%%= render partial: "button", collection: %w[👑 🎩 👒 🧢 ⛑️ 👓 🕶️ 🥽 💄 📣 👄 💧 👅 👂 👃 👁️ ☂️ 👍 🖕 👋], as: :emoji %>
      </ul>
    </div>
  </div>
</div>

The canvas handles mouse events for selecting and dragging emojis. On the right I added the emoji picker with faces, accessories and body parts. Each emoji button gets rendered through a simple partial:

<%%# locals: (emoji:) %>
<li>
  <button data-emoji="<%%= emoji %>" data-action="canvas-composer#addEmoji">
    <%%= emoji %>
  </button>
</li>

HTML Canvas?

Before diving into the Stimulus controller, let's talk about the <canvas> element. Canvas provides a drawing surface where you can render graphics, text and images using JavaScript. Think of it as a blank piece of paper that your code can draw on.

Canvas uses a coordinate system starting from the top-left corner (0,0). The x-axis runs left to right, y-axis runs top to bottom. No surprise here! To draw on canvas, you get its 2D rendering context and use methods like fillText(), drawImage() and clearRect().

What makes canvas perfect for this emoji composer? You can draw text (emojis) at specific positions, clear and redraw the entire canvas efficiently and export the final result as an image. Canvas also handles layering naturally. Elements drawn later appear on top.

The key canvas methods you'll see:

getContext("2d") - gets the drawing context
clearRect() - clears a rectangular area
fillText() - draws text at specified coordinates

The Stimulus controller

The main controller manages the emoji canvas and drag-and-drop functionality:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["canvas"]
  static values = { emojiSize: { type: Number, default: 100 } }

  #emojisOnCanvas = []
  #selectedEmoji = null
  #isDragging = false
  #dragOffset = { x: 0, y: 0 }

  connect() {
    this.#redrawCanvas()
  }
}

The controller tracks emojis on the canvas, which emoji is currently selected, drag state and the offset for smooth dragging. Of course private methods as you are used to from me.

Adding emojis to the canvas

When you click an emoji button, it gets added to the center of the canvas:

addEmoji(event) {
  const center = this.#canvasCenter
  const emoji = {
    text: event.target.dataset.emoji,
    x: center.x - this.emojiSizeValue / 2,
    y: center.y - this.emojiSizeValue / 2,
    width: this.emojiSizeValue,
    height: this.emojiSizeValue,
    fontSize: this.emojiSizeValue,
    id: Date.now() + Math.random()
  }

  this.#emojisOnCanvas.push(emoji)

  this.#redrawCanvas()
}

Each emoji becomes an object with position, size and a unique ID. The emoji gets centered by subtracting half its size from the center coordinates. After adding it to the array, the canvas redraws to show the new emoji.

Drag and drop interaction

The drag system uses three mouse events: mousedown to select, mousemove to drag and mouseup to release:

selectEmoji(event) {
  const coordinates = this.#eventToCanvasCoordinates(event)
  this.#selectedEmoji = this.#emojiAtPosition(coordinates.x, coordinates.y)

  if (this.#selectedEmoji) {
    this.#isDragging = true
    this.#dragOffset = {
      x: coordinates.x - this.#selectedEmoji.x,
      y: coordinates.y - this.#selectedEmoji.y
    }

    this.canvasTarget.style.cursor = "grabbing"
  }
}

moveSelectedEmoji(event) {
  if (!this.#isDragging || !this.#selectedEmoji) return

  const coordinates = this.#eventToCanvasCoordinates(event)
  this.#selectedEmoji.x = coordinates.x - this.#dragOffset.x
  this.#selectedEmoji.y = coordinates.y - this.#dragOffset.y

  this.#redrawCanvas()
}

deselectEmoji() {
  this.#isDragging = false
  this.#selectedEmoji = null
  this.canvasTarget.style.cursor = "default"
}

The drag offset prevents emojis from jumping when you start dragging. Without it, the emoji would snap so its top-left corner sits under your mouse. With the offset, it maintains its relative position to your cursor. Smooth.

Helper methods for canvas operations

Several private methods handle the canvas coordinate system and rendering:

get #canvasContext() {
  return this.canvasTarget.getContext("2d")
}

get #canvasCenter() {
  return {
    x: this.canvasTarget.width / 2,
    y: this.canvasTarget.height / 2
  }
}

#eventToCanvasCoordinates(event) {
  const rect = this.canvasTarget.getBoundingClientRect()

  return {
    x: event.clientX - rect.left,
    y: event.clientY - rect.top
  }
}

#emojiAtPosition(x, y) {
  return [...this.#emojisOnCanvas].reverse().find(emoji =>
    x >= emoji.x && x <= emoji.x + emoji.width &&
    y >= emoji.y && y <= emoji.y + emoji.height
  )
}

The coordinate conversion is important because mouse events give you screen coordinates, but canvas needs relative coordinates. The getBoundingClientRect() method provides the canvas position on screen.

Finding emojis at a position uses reverse order so top emojis get selected first. The hit detection checks if the click falls within the emoji's bounding box.

Drawing on the canvas

The redraw method clears the canvas and renders all emojis:

#redrawCanvas() {
  this.#canvasContext.clearRect(0, 0, this.canvasTarget.width, this.canvasTarget.height)

  this.#emojisOnCanvas.forEach(emoji => {
    this.#canvasContext.font = `${emoji.fontSize}px Arial`
    this.#canvasContext.fillText(emoji.text, emoji.x, emoji.y + emoji.fontSize * 0.8)
  })
}

Canvas text positioning is tricky. The y-coordinate represents the baseline, not the top of the text. Adding fontSize * 0.8 moves the text down so it appears where you expect it visually.

Canvas performance and browser support

Canvas has excellent browser support and performs well for this type of application. The clear-and-redraw approach might seem inefficient, but modern browsers optimize canvas operations heavily.

For emoji rendering, canvas handles Unicode characters beautifully. Emojis render as text, so they scale cleanly and look crisp at any size. The font size directly controls the emoji size.

One consideration: canvas is a raster format, so exported images have fixed resolution. For crisp results on high-DPI displays, you might want to scale up the canvas and export at higher resolution.

This was too much fun to build and even more fun to actually use. The combination of canvas drawing, drag-and-drop interaction and image export creates something genuinely fun to use. See images above. 😊

Try building your own custom emoji and see what combinations you come up with! The possibilities are endless when you have a canvas and some creativity.

Video Preview on Hover with Stimulus

Rails Designer — Thu, 12 Mar 2026 17:15:00 +0000

This article was originally published on Rails Designer's blog

Building on the video recording feature from earlier, let's add a nice touch to the presentation index page: video previews that play on hover. You know the experience—hover over a video thumbnail and get a quick preview of what's inside. It's the same interaction you see on YouTube, Netflix and every modern video platform.

The presentations index

After recording presentations, you need a way to browse them. A simple index page lists all presentations with video thumbnails. When you hover over a thumbnail, the video plays a preview. Move your cursor away and it returns to the poster image.

Here's the basic setup:

<% @presentations.each do |presentation| %>
  <%= video_tag presentation.video,
    width: "160",
    poster: (presentation.video.representable? ? url_for(presentation.video.representation(resize: "160x120")) : nil),
    data: {
      controller: "preview",
      action: "mouseenter->preview#play mouseleave->preview#pause"
    }
  %>
<% end %>

Active Storage's representable? method checks if a preview can be generated and representation() creates the thumbnail automatically.

The preview controller

All the logic happens in one Stimulus controller:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = {
    segments: { type: Number, default: 3 },
    interval: { type: Number, default: 1000 },
    minDuration: { type: Number, default: 5 }
  }

  connect() {
    this.originalTime = 0
    this.wasPlaying = false
    this.previewTimer = null
    this.currentIndex = 0
    this.isReady = false
    this.timestamps = []

    this.element.addEventListener("loadedmetadata", () => {
      this.#calculateTimestamps()

      this.isReady = true
    })
  }
}

Understanding loadedmetadata

The loadedmetadata event is the key here. It fires when the browser has loaded enough of the video to know its duration, dimensions and other metadata. Without this information, you can't calculate meaningful preview timestamps.

this.element.addEventListener("loadedmetadata", () => {
  this.#calculateTimestamps()
  this.isReady = true
})

Only after loadedmetadata fires can you access this.element.duration reliably. Try to use it before this event and you'll get NaN or 0.

Smart timestamping

Instead of just playing from the beginning, the controller shows different parts of the video:

#calculateTimestamps() {
  const duration = this.element.duration

  if (duration < this.minDurationValue) {
    this.timestamps = [0]
    return
  }

  this.timestamps = []
  for (let i = 1; i <= this.segmentsValue; i++) {
    this.timestamps.push((duration / (this.segmentsValue + 1)) * i)
  }
}

For short videos (under 5 seconds), it just plays from the start. For longer videos, it divides the duration into segments and cycles through them. A 60-second video with 3 segments shows clips at 15, 30 and 45 seconds.

The element methods

Stimulus gives you direct access to the video element through this.element. Here are the key methods and properties used:

this.element.duration for the total video length in seconds
this.element.currentTime for current playback position
this.element.paused is a boolean indicating if video is paused
this.element.play() to start playback
this.element.pause() to pause playback
this.element.muted is a boolean to control audio during preview

The preview controller leverages these to create smooth hover interactions:

play() {
  if (!this.isReady || this.timestamps.length === 0) return

  this.originalTime = this.element.currentTime
  this.wasPlaying = !this.element.paused
  this.currentIndex = 0

  this.element.muted = true
  this.#showNextTimestamp()

  if (this.timestamps.length > 1) {
    this.previewTimer = setInterval(() => {
      this.#showNextTimestamp()
    }, this.intervalValue)
  }
}

When you hover, it saves the current state, mutes the audio and starts cycling through preview segments. When you leave, it restores everything exactly as it was.

Auto-looping previews

The preview automatically loops through different parts of the video:

#showNextTimestamp() {
  this.element.currentTime = this.timestamps[this.currentIndex]
  this.element.play()

  this.currentIndex = (this.currentIndex + 1) % this.timestamps.length
}

The modulo operator (%) creates the loop: when it reaches the last segment, it goes back to the first. Combined with setInterval, this creates a cycling preview that gives your users a real sense of the video content.

The key is waiting for the right moment (when metadata loads), calculating smart preview points and cleaning up properly when the interaction ends. This preview controller shows how a small Stimulus controller can create a nice UX. By understanding browser events like loadedmetadata and leveraging the video element's built-in methods, you can get a lot done without writing a lot of JavaScript. 🥳

Welcome to a new Rails Designer

Rails Designer — Thu, 05 Mar 2026 17:15:00 +0000

In January 2024 I published the first article on Rails Designer's blog. It listed some of my best practices; most of which I still use today.

Over those two years there were almost 200 articles published on topics ranging from Hotwire, to Rails and Tailwind CSS. Next to that I've launched various tools and dozen open source projects. With all those articles, tools and other pages, the site slowly started to feel incoherent. Less consistent in style, feel and branding. So it was time to lose some weight and put on some fresh clothes! 🎩💅

I spent some time recently to build the site from scratch. Not coincidentally this was a good time to build it using Perron, the Rails-based static site generator I launched about seven months ago. If you haven't checked it out, please do! I think you will like it for your next marketing site, docs or landing page.

Have a look around.

Over time I will tighten things here and there, but if you find glaring issues or certain missing, please comment below. 😊

If you want to read about the tech details, continue reading! 👇

Building a medium-sized site with Perron

Rails Designer's site is built with Perron. It is the Rails-based SSG. While that certainly might sound weird (isn't Rails way too big for just static sites?!), it is surprising lean and fast to work with.

I develop the site, rendering the site runningrails server (bin/dev). Perron, via the new Mata gem auto-refreshes the page, making it easy to see what I fixed (or messed up). Once I am ready to publish, I run bin/rails perron:build and, presto: you are looking at the static-build site.

Most of the standard Rails libraries are disabled, the only ones added are:

# config/application.rb
require_relative "boot"

require "active_model/railtie"
require "action_controller/railtie"
require "action_view/railtie"

Bundler.require(*Rails.groups)

module RailsDesigner
  class Application < Rails::Application
  # …

Perron works with collections, like posts, articles or features. Those you are likely familiar with you already. Let's look at the posts collection, for example.

First the routes:

Rails.application.routes.draw do
  resources :articles, module: :content, path: "components/docs", only: %w[index show]
  resources :changelogs, module: :content, path: "components/changelog", only: %w[index]
  resources :components, module: :content, only: %w[index show]

  get "version.json", to: "content/versions#show", as: :version

  # ✂️

  resources :posts, module: :content, path: "articles", only: %w[index show]

  # ✂️

  root to: "content/pages#root"
end

These are just Rails' routes you are already familiar with, right?! Let's see the Content::PostsController:

class Content::PostsController < ApplicationController
  def index
    @metadata = {
      # …
    }

    @resources = Content::Post.all
  end

  def show
    @resource = Content::Post.find!(params[:id])
  end
end

Also just vanilla Rails here! Then one more step: the views. First the index view:

<%= component "hero", heading: "Rails UI Engineering Articles", description: "\"Practical guides to build better Rails UI. I share the patterns and approaches I use in my daily work with Hotwire, Rails and modern front-end practices.\" %>"

<%= component "container" do %>
  <section class="grid gap-y-2">
    <%= component("heading") { "Latest articles" } %>

    <ul class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:gap-6">
      <%= render partial: "post_card", collection: @resources.recently_published.limit(4), as: :post %>
    </ul>
  </section>

  <section class="mt-8 md:mt-10">
    <%= component("heading") { "Popular articles" } %>

    <p class="mt-0.5 text-sm text-gray-600 lg:text-base">
      Based on views using the Wilson Score with time decay.
    </p>

    <ol class="grid grid-cols-1 gap-4 mt-4 md:grid-cols-2 lg:gap-6">
      <%= render partial: "post_card", collection: @resources.featured.limit(4), as: :post %>
    </ol>
  </section>

  <!-- ✂️ -->

Pretty clean and still looks like your average Rails view. How about the show template?

<article>
  <%= component "hero", heading: @resource.title %>

  <%= component("container", additional_css: "grid grid-cols-12 lg:gap-20") do %>
    <div class="col-span-12 content md:col-span-9">
      <%= markdownify @resource.content, process: ["lazy_load_images", CopyableCodeProcessor, StyledBlockquoteProcessor, NofollowProcessor, AbsoluteImagesProcessor] %>
    </div>

    <%= render "content/posts/aside", resource: @resource %>
    <%= render "content/posts/dialog", resource: @resource %>
    <%= render "content/posts/comments" %>

    <section class="col-span-12 px-2 py-3 bg-gray-50 border border-gray-100 rounded-lg md:col-span-9 md:px-4 md:py-6 max-md:mt-8">
      <%= component("heading", level: :h2) { "Want to read me more?" } %>

      <ul class="grid gap-y-4 mt-4">
        <%= render partial: "content/posts/post", collection: @resource.related_resources(limit: 3), as: :post, locals: { description: "true } %>"
      </ul>
    </section>
  <% end %>
</article>

See how resources, which are erb or markdown files stored in app/content/posts, use recently_published, featured and limit? Those are, indeed, scopes defined on the content/post model:

# app/models/content/post.rb
class Content::Post < Perron::Resource
  include Categories

  configure do |config|
    config.feeds.atom.enabled = true

    # …

    config.sitemap.priority = 0.4
  end

  delegate :title, :description, :category, :section, :featured, :updated_at, to: :metadata

  scope :featured, -> { where(featured: true) }
  scope :recently_published, -> { order(published_at: :desc) }
  scope :earliest_published, -> { order(published_at: :asc) }

  validates :category, inclusion: {in: Content::Post::CATEGORIES.keys.map(&:to_s)}, if: -> { section == "general" }
end

The only thing you notice that is different from a regular Active Model resource is the parent class: Perron::Resource, but otherwise it “quacks” much the same.

Auto pull data to create resources

Perron offers many features on top it all, like feeds, sitemap and data resource handling. The latter is one I like to highlight now.

I like to list all the open source projects I built and maintain. I am ashamed to admit that previously I built all these pages manually. I just never came around automating it. But also: my previous SSG didn't have a clear way of doing. Perron does, via the programmatic content feature.

This is how it works. I list all projects I want to include in app/content/data/tools.yml:

- id: rails-icons
  name: Rails Icons
  github_url: https://github.com/rails-designer/rails_icons
  category: oss
  position: 1
  package_registry_url: https://rubygems.org/gems/rails_icons
- id: courrier
  name: Courrier
  category: oss
  github_url: https://github.com/rails-designer/courrier
  package_registry_url: https://rubygems.org/gems/courrier
- id: icons
  name: Icons
  category: oss
  github_url: https://github.com/rails-designer/icons
  package_registry_url: https://rubygems.org/gems/icons
- id: mata
  name: Mata
  category: oss
  github_url: https://github.com/rails-designer/mata
  package_registry_url: https://rubygems.org/gems/mata
- id: requestkit
  name: Requestkit
  category: oss
  github_url: https://github.com/rails-designer/requestkit
  package_registry_url: https://rubygems.org/gems/requestkit
- id: turbo-transition
  name: Turbo Transition
  category: oss
  github_url: https://github.com/rails-designer/turbo-transition
  package_registry_url: https://www.npmjs.com/package/turbo-transition
// …

I then define the template:

class Content::Tool < Perron::Resource
  include GithubFetch, RubygemsFetch

  source :tools

  # …

  def self.source_template(sources)
    tool = sources.tools

    return if tool.respond_to?(:url) && tool.url.present?

    <<~TEMPLATE
      ---
      category: #{tool.category}
      title: #{tool.name}
      description: #{description_for(tool)}
      github_url: #{tool.github_url}
      github_stars: #{stars_for(tool)}
      package_registry_url: #{tool.package_registry_url}
      package_downloads: #{downloads_for(tool)}
      ---

      #{content_for(tool)}
    TEMPLATE
  end
end

GithubFetch and RubygemsFetch have some custom logic to pull the required data, looking something like this:

module Content::Tool::GithubFetch
  extend ActiveSupport::Concern

  class_methods do
    private

    def description_for(tool)
      return tool.description if tool.respond_to?(:description) && tool.description.present?

      github_data(tool.github_url)[:description]
    end

    def stars_for(tool)
      github_data(tool.github_url)[:stars]
    end

    # …
  end
end

Then all that is need is run bin/rails perron:sync_sources[tools] to update all content and stars + downloads:

bin/rails perron:sync_sources
Fetching RubyGems downloads for rails_icons…
Fetching README for rails-designer/rails_icons…
Fetching RubyGems downloads for courrier…
Fetching README for rails-designer/courrier…
Fetching RubyGems downloads for icons…
Fetching README for rails-designer/icons…
Fetching RubyGems downloads for mata…
Fetching README for rails-designer/mata…
Fetching RubyGems downloads for requestkit…
Fetching README for rails-designer/requestkit…
Fetching NPM downloads for turbo-transition…
Fetching README for rails-designer/turbo-transition…
# …

Pretty cool, right? 😊 I am pretty pleased with it at all.

Let me know if you want me to highlight any other thing below in the comments. And if you want big holes or odd rendering issues, do let me know as well. ❤️

Understanding importmap-rails

Rails Designer — Thu, 26 Feb 2026 17:15:00 +0000

This article was originally published on Rails Designer

If you've worked with modern JavaScript, you're familiar with ES modules and import statements. Rails apps can use esbuild (or vite or bun) for this, but the default option (Rails way) is importmap-rails. It lets you write import { Controller } from "@hotwired/stimulus" without any build step at all.

Ever thought about how this works?

Import maps, just a web standard

Import maps are a web standard that tells browsers how to resolve bare module specifiers. A bare module specifier looks like import React from "react", which isn't valid ESM on its own. The browser needs an absolute path (/assets/react.js), relative path (./react.js), or HTTP URL (https://cdn.example.com/react.js).

Import maps provide the translation:

<script type="importmap">
{
  "imports": {
    "application": "/assets/application-abc123.js",
    "@hotwired/stimulus": "/assets/stimulus.min-def456.js",
    "controllers/application": "/assets/controllers/application-ghi789.js"
  }
}
</script>

When your JavaScript says import { Controller } from "@hotwired/stimulus", the browser looks up "@hotwired/stimulus" in this map and loads /assets/stimulus.min-def456.js.

The importmap-rails gem generates this script tag for you. It appears in your layout via <%= javascript_importmap_tags %>, which reads your config/importmap.rb configuration and outputs the importmap along with modulepreload links (which tell the browser to start downloading your JavaScript files immediately, rather than waiting to discover each import one at a time) and your application entry point.

Configuring with pin

In config/importmap.rb, you define what goes in that map:

pin "application"
pin "@hotwired/turbo-rails", to: "turbo.min.js"
pin "@hotwired/stimulus", to: "stimulus.min.js"
pin "@rails/request.js", to: "@rails--request.js.js"

Each pin creates a mapping (entry) in the importmap. The first argument is the bare module specifier you'll write in your import statement. The to: attribute specifies which file should be loaded from your asset pipeline (typically from app/javascript or vendor/javascript).

To add a package from npm, run:

./bin/importmap pin package-name

This downloads the package file into vendor/javascript and adds the pin to your config/importmap.rb. The default is to use JSPM.org as the CDN, but you can specify others:

./bin/importmap pin react --from unpkg
./bin/importmap pin react --from jsdelivr

The downloaded files are checked into your source control and served through your application's asset pipeline.

Mapping directories with pin_all_from

Instead of pinning files individually, you can map entire directories:

pin_all_from "app/javascript/controllers", under: "controllers"
pin_all_from "app/javascript/turbo_stream_actions", under: "turbo_stream_actions"

The under: attribute creates a namespace prefix. Every file in the directory becomes “importable” with that prefix.

So app/javascript/controllers/reposition_controller.js becomes:

import RepositionController from "controllers/reposition_controller"

And app/javascript/turbo_stream_actions/set_data_attribute.js becomes:

import set_data_attribute from "turbo_stream_actions/set_data_attribute"

Example: custom Turbo Stream actions

Let's now look at how all these pieces connect. Say you want to register a custom Turbo Stream action (as I wrote about here and here).

First, in config/importmap.rb, you map the directory:

pin_all_from "app/javascript/turbo_stream_actions", under: "turbo_stream_actions"

When Rails generates the importmap (via <%%= javascript_importmap_tags %>), it scans that directory and creates entries for each file:

{
  "imports": {
    "turbo_stream_actions": "/assets/turbo_stream_actions/index-abc.js",
    "turbo_stream_actions/set_data_attribute": "/assets/turbo_stream_actions/set_data_attribute-xyz.js"
  }
}

Now you can create your custom action at app/javascript/turbo_stream_actions/set_data_attribute.js:

export default function() {
  // your custom logic
}

And register it in app/javascript/turbo_stream_actions/index.js:

import set_data_attribute from "turbo_stream_actions/set_data_attribute"

Turbo.StreamActions.set_data_attribute = set_data_attribute

The browser sees "turbo_stream_actions/set_data_attribute", looks it up in the importmap, finds /assets/turbo_stream_actions/set_data_attribute-xyz.js, and loads it.

Finally, in your main app/javascript/application.js:

import "turbo_stream_actions"

Your custom action is now registered. The import path ("turbo_stream_actions/set_data_attribute") matches the under: namespace from your pin_all_from configuration.

How Stimulus controllers use this

The same pattern is used for Stimulus. In config/importmap.rb:

pin_all_from "app/javascript/controllers", under: "controllers"

The under: value here could be anything: "my_controllers" or "stimulus_controllers". But "controllers" is the convention. It becomes the import prefix for everything in that directory.

In app/javascript/controllers/index.js:

import { application } from "controllers/application"
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"

eagerLoadControllersFrom("controllers", application)

The application import comes from app/javascript/controllers/application.js:

import { Application } from "@hotwired/stimulus"

const application = Application.start()
application.debug = false
window.Stimulus = application

export { application }

The eagerLoadControllersFrom function scans the importmap for entries starting with "controllers/" and automatically imports and registers them. Add a new controller file and it's instantly available.

Because of pin_all_from with under: "controllers", the file app/javascript/controllers/application.js is “importable” as "controllers/application". The pattern is the same: directory structure maps to import paths through the under: namespace.

Simplifying timestamp toggles in Rails

Rails Designer — Tue, 24 Feb 2026 17:15:00 +0000

This article was originally published on Rails Designer's Build a SaaS Blog

I often use timestamps, like completed_at as a boolean flag. It offers just a bit more (meta) data than a real boolean.

But of course on the UI you want to show a checkbox that a user can toggle instead of a datetime field.

I have done this often enough, that I created a simple concern that I use throughout my apps. Given above completed_at example, it gives you an API like:

@resource.completed?
@resource.complete!
@resource.complete=

So in your form, you can simply use form.check_box :completed and you're off.

The concern is simple enough:

# lib/boolean_attributes.rb
module BooleanAttribute
  extend ActiveSupport::Concern

  class_methods do
    def boolean_attribute(*fields)
      fields.each do |field|
        column = :"#{field}_at"

        define_method(field) { public_send(column).present? }

        define_method("#{field}?") { public_send(column).present? }

        define_method("#{field}=") do |value|
          public_send("#{column}=", ActiveModel::Type::Boolean.new.cast(value) ? Time.current : nil)
        end

        define_method("#{field}!") { update!("#{column}": Time.current) }
      end
    end
  end
end

In your model use it like this:

class Task < ApplicationRecord
  include BooleanAttributes

  boolean_attribute :completed

  # …
end

It is just that little concerns that make your life a bit easier.