• hide the feature if the customer does not have access;
• show all features, to all customers, but guard them with some, optional, upsell.

I have succesfully implementated the latter approach with a helper that quacks like Rails itself.

The helper lets you wrap content and decide what happens when access is denied. Hide it, redirect to a link, render content or render a partial. It’s small but flexible. This is how it looks (added a toggle allowed/denied states):

As always view on GitHub for a ready-to-copy code.

The API is elegant. Let’s look at some examples:

<%= allowed? Current.user.premium? do %>
  <%= link_to "Create project", projects_path %>
<% end %>

When Current.user.premium? is true, the link renders. When false, nothing shows. That’s the default behavior.

But you can do more. Redirect to a link instead:

<%= allowed? Current.user.premium?, redirect_to: upgrade_path do %>
  <%= link_to "Advanced analytics", analytics_path %>
<% end %>

The content becomes a clickable link pointing to your upgrade page.

Show plain text as a fallback:

<%= allowed? Current.user.premium?, render: { plain: "Upgrade to unlock this." } do %>
  <%= button_to "Delete project", project_path, method: :delete %>
<% end %>

Or render HTML:

<%= allowed? Current.user.premium?, render: { html: "Upgrade to the <strong>Pro plan</strong>." } do %>
  <%= button_to "Delete project", project_path, method: :delete %>
<% end %>

And render a partial for complex fallbacks:

<%= allowed? Current.user.premium?, render: "upsell" do %>
  <%= button_to "Advanced settings", settings_path %>
<% end %>

The helper

Here’s the full helper in app/helpers/allowed_helper.rb:

module AllowedHelper
  def allowed?(condition, options = {})
    return yield if condition

    if options[:redirect_to]
      content = capture { yield }

      link_to strip_tags(content), options[:redirect_to]
    elsif options.key?(:render)
      render_options = options[:render]

      if render_options.is_a?(Hash) && render_options.key?(:html)
        render_options[:html].html_safe
      elsif render_options.is_a?(Hash) && render_options.key?(:plain)
        render_options[:plain]
      else
        render({ partial: render_options.to_s }) if render_options.is_a?(String) || render_options.is_a?(Symbol)
      end
    end
  end
end

The logic is straightforward. If the condition is true, render the block. If false, check your options and handle it accordingly.

When you pass redirect_to, it captures the block content, strips HTML tags and wraps it in a link. When you pass render, it supports three formats: plain text, raw HTML or a partial name as a string or symbol.

This helper did, ~10 years ago, not start like this. Over the years, after working on many dozens Rails-based SaaS apps, my aim became to make helpers “quack” more like Rails methods. You’re familiar with render plain:, render html: and partial rendering. This helper just extends that familiar syntax to conditional rendering.

I like it. What do you think of this?

Perron, the Rails-based SSG, has a library of production-ready custom elements. One of them, the Embed Content component is perfect for this exact use case. It fetches JSON data, renders it as a list, tracks read state and handles all the UI interactions. You just provide the data.

The result will look like this:

Pretty smooth, right?

Most changelog services lock you into their platform. You pay per seat, deal with their branding and accept their feature set. If you want something simpler or more tailored to your product, you’re stuck building it from scratch.

But here’s the thing: a changelog widget isn’t complicated. It needs to fetch some data, display it nicely, track which items users have read and maybe show a badge with unread counts. That’s it. The Embed Content component is a custom element that fetches JSON from any endpoint, renders items with a template you control, tracks unread state based on a last-read-at timestamp, shows an unread badge automatically and handles open/close toggle states.

You drop it into your HTML, point it at your changelog endpoint and it works. You write the changelog entries in your Perron site (where they are also published. Win-win! 🏆).

Getting Started

First, add the Embed Content component to your project. The setup instructions are straightforward: run the template in your app and the custom element is ready to use.

Next, you’ll need a JSON feed. Perron makes this easy: check out the Perron docs to see how to create a custom template that outputs your changelog items as JSON.

Once your feed is live, drop the Embed Content component into your view:

<embed-content id="changelog-widget" src="https://example.com/changelog.json" limit="5" last-read-at="2026-03-20T00:00:00Z">
  <button aria-label="Toggle changelog">
    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
      <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9"/>
      <path d="M10.3 21a1.94 1.94 0 0 0 3.4 0"/>
    </svg>

    <span badge></span>
  </button>

  <div panel>
    <div header>
      <h2>What's new</h2>
    </div>

    <ul items></ul>
  </div>
</embed-content>

The component reads the src attribute, fetches your JSON and renders each item. The limit attribute controls how many items show. The last-read-at attribute tracks which items are new: anything published after that timestamp gets marked as unread and counted in the badge.

Your feed doesn’t have to come from Perron. The component just needs JSON with title, body, url and published_at fields. You could use a custom Rails endpoint, a headless CMS or any JSON API. The pattern is the same.

The component uses semantic HTML and CSS custom properties, so styling is straightforward. You control the colors, spacing and layout. This pattern works for any feed-like feature: product announcements, status updates, notification centers or feature releases. The Embed Content component handles the hard parts. You focus on your content. ✨

Check out the example repository for the complete example including CSS.

If you feel generous, head over to the GitHub repo and give it a star! 🌟

Installation and configuration

To install Beam Up, run:

gem install beam_up

Then initialize a configuration file for your chosen provider with:

beam_up init # to start an interactive process, or:
# beam_up init hetzner

This creates a .beam_up.yml file:

provider: netlify
netlify:
  api_token: your_token_here
  project_id: your_project_id

Ready to beam ⚡

Now you can deploy your static site using the super fun beam_up command:

beam_up ./output

Beam Up supports multiple providers including AWS S3, Seal Static, Hetzner, Netlify and Statichost. Oh, and it even works with SFTP (remember those days?!).

Usage from Ruby

Beam Up can also be used within Ruby scripts:

require "beam_up"

BeamUp.deploy! "./output"

Integration with Perron

While Beam Up is designed to work with any SSG (Jekyll, Middleman or Bridgetown), I built it for Perron. With the latest version, you can now simply run bin/rails perron:deploy, it will build your site (bin/rails perron:build) and deploy it: your site will be live in no time. Without any config, it will default to deploy to Seal Static (where an account is created for you on first deploy). Cool, right? 😎

Beam Up is a small, new OSS project made with ❤️ from Rails Designer HQ. If you like it, do star it on GitHub and give it a try on your (next) SSG project.

Ever thought of building one from scratch? Not complicated at all! In this article, I want to show how to build a simple, reusable Stimulus controller that does just all that. This is how the end result will look like:

As always, the code can be found on GitHub.

It is simple, really

The beauty of this controller is its simplicity. You need three things:

• a wrapper element;
• two images (before and after), and;
• a slider.

That’s it. Here’s it in HTML:

<div data-controller="compare">
  <img data-compare-target="before" src="before.jpg">
  <img data-compare-target="after" src="after.jpg">

  <div data-compare-target="slider"></div>
</div>

The two images are positioned absolutely and the slider sits on top as a draggable handle. The “after” image gets clipped dynamically as you drag.

Here’s that interesting part. It uses clip-path to reveal or hide the after image:

set #position(value) {
  this.positionValue = value
  this.sliderTarget.style.left = `${value * 100}%`
  this.afterTarget.style.clipPath = `inset(0 0 0 ${value * 100}%)`
}

When you drag the slider, it calculates the position relative to the container’s width, then updates both the slider’s left position and the clip-path of the after image. Most of that is done with:

#pointerDown = (event) => {
  if (event.target !== this.sliderTarget) return

  event.preventDefault()

  document.addEventListener("pointermove", this.#pointerMove)
  document.addEventListener("pointerup", this.#pointerUp)
}

Stimulus controllers are meant to be reusable

This controller is a wrapper element plus two images. That’s it. Use cases then are limitless (they generally work great on marketing blogs as well!):

• product photography; show different angles or colors of the same product
• photo editing results; before/after with filters, adjustments, or retouching
• UI redesigns; old interface vs. new interface

You could (should) extend this in several directions. Add keyboard support for accessibility. Include labels (“Before” / “After”) that move with the slider. Add touch support with haptic feedback on mobile.

It is the kind of controller you copy and paste into your projects. Just as it should be.

The quiz loads questions from a Rails endpoint, tracks answers in real-time, calculates results and submits them to your server. As always, the code can be found on GitHub.

This will be the result. Time to dust off that good ol’ computer science knowledge… 🤓

Building the data class

Here’s the QuizData class that handles the quiz logic. For this example it lives inside the Stimulus controller, but you can organise it however you want.

class QuizData {
  constructor(questions) {
    this.questions = questions
    this.answers = {}
  }

  answer(questionIndex, selectedOption) {
    this.answers[questionIndex] = selectedOption
  }

  getAnswer(questionIndex) {
    return this.answers[questionIndex]
  }

  correctCount() {
    return this.questions.filter((question, questionIndex) => {
      const answer = this.answers[questionIndex]
      return answer !== undefined && answer === question.correct
    }).length
  }

  result() {
    return this.questions.reduce((accumulate, question, questionIndex) => {
      const answer = this.answers[questionIndex]

      return accumulate + ((answer === question.correct) ? Math.pow(2, this.questions.length - 1 - questionIndex) : 0)
    }, 0)
  }

  get totalQuestions() {
    return this.questions.length
  }

  get isComplete() {
    return Object.keys(this.answers).length === this.totalQuestions
  }

  static default() {
    return new QuizData([
      {
        question: "What is \"Hi\" in binary?",
        options: ["01001000 01101001", "01000111 01101001", "01001000 01110011", "01000001 01101001"],
        correct: 0
      },

      // more questions…
    ])
  }
}

This class provides methods to record answers, checks if all questions are answered and calculate the score and encode results. The result() method is a little bit clever, it encodes which questions were answered correctly as a binary number, making it easy to store and analyze results server-side.

The static default() method provides quiz data if you do not have a remote endpoint so you can use it also outside of a Rails app (in a static site, for example).

The Rails endpoint

Your quiz questions need to come from somewhere. Create a QuizzesController with an index action that returns questions as JSON:

class QuizzesController < ApplicationController
  def index
    render json: {
      questions: [
        {
          question: "What is \"Hi\" in binary?",
          options: ["01001000 01101001", "01000111 01101001", ...],
          correct: 0
        },

        # etc…
      ]
    }
  end

  def create
    Rails.logger.info "Quiz submission: #{params.permit!.to_h}"

    head :ok
  end
end

The index action returns an array of questions with their options and the index of the correct answer. The create action receives the submitted answers, you can process them here however you want (send along, store in DB, etc.).

The Stimulus controller

Now the Stimulus where it all happens 🛏️✨. This controller fetches questions from your endpoint, renders them and handles user interactions. It uses the @rails/request.js library to make clean HTTP requests.

When the controller connects, it fetches the questions:

async connect() {
  this.quiz = await this.#getQuestions()

  this.#render()
}

async #getQuestions() {
  if (this.hasQuestionsEndpointValue) {
    try {
      const response = await get(this.questionsEndpointValue, { responseKind: "json" })

      if (response?.questions?.length > 0) return new QuizData(response.questions)
    } catch (error) {
      console.warn("Failed to load questions from endpoint, using defaults:", error)
    }
  }

  return QuizData.default()
}

This check this.hasQuestionsEndpointValue is added so I can use this controller also outside of a Rails app.

When a user selects an answer, the controller records it and enables the submit button (when all questions are answered):

selectAnswer(event) {
  const optionsContainer = event.target.closest("[data-quiz-question-index]")
  const questionIndex = parseInt(optionsContainer.dataset.quizQuestionIndex, 10)
  const selectedOption = parseInt(event.target.value, 10)

  this.quiz.answer(questionIndex, selectedOption)
  this.submitTarget.disabled = !this.quiz.isComplete
}

When the user submits the quiz, the controller sends the answers and result to your Rails endpoint. For details on how @rails/request.js works and how to make GET and POST requests from a Stimulus controller, check out this article 😊. What is happening is that you’re sending structured data (answers and a calculated result) to your server:

async submit() {
  const payload = {
    answers: this.quiz.answers,
    result: this.quiz.result()
  }

  if (this.hasAnswersEndpointValue) {
    await post(this.answersEndpointValue, {
      body: JSON.stringify(payload)
    })
  }

  this.#showResults()
}

After submission, the controller displays the results and hides the quiz:

#showResults() {
  const correct = this.quiz.correctCount()
  const total = this.quiz.totalQuestions

  const fieldsets = this.element.querySelectorAll("fieldset")
  fieldsets.forEach(fieldset => fieldset.remove())

  this.resultsTarget.innerHTML = `<div>${correct} out of ${total} correct</div>`
  this.submitTarget.hidden = true
}

The HTML view is minimal:

<article data-controller="quiz" data-quiz-questions-endpoint-value="<%= quizzes_path %>" data-quiz-answers-endpoint-value="<%= quizzes_path %>">
  <output data-quiz-target="results"></output>

  <button type="button" data-quiz-target="submit" data-action="quiz#submit" disabled>Submit Quiz</button>
</article>

The controller renders each question as a fieldset with radio buttons. The styling uses modern CSS (oklch color space; see this article, CSS Grid) to create a clean, accessible interface. The CSS isn’t included here, but it handles the layout, hover states and checked states for the radio buttons.

This quiz is a good starting point. You could add pagination to show only a few questions at a time, add a countdown timer that auto-submits when time runs out, send detailed results to an analytics service to track which questions trip up your users, allow retakes so users can compare scores over time or fetch different question sets based on difficulty level.

Most live reload solutions either require ActionCable (overkill when using Perron) or just do full-page reloads (annoying/too minimal). I wanted something in between.

Meet Mata: a lightweight live reload solution for Rack apps. It uses Server-Sent Events (SSE) and idiomorph.

You can install Mata simply by running bundle add mata --group=development. Then configure the middleware with watch and skip paths. That’s it. No JavaScript bundling. No ActionCable. No WebSockets. Just smart live reloading! ✨

But Mata isn’t just for Perron. It works with any Rack-based framework, like Rails: Sinatra, Hanami or Roda. 🚀 See the GitHub README for set up examples.

Look, mom, no hands:

So why the name? It’s named after the legendary double agent: Mata Hari. 🕵️💃🤓

(oh, I learned while in Indonesia, in Bahasa Indonesia, mata means eye. A fun coincidence, for something that watches your files. 😅)

Already using Mata (you do if you use Perron!)? Give Mata a star on GitHub. ⭐❤️

It will look a little something like this:

This article walks through how I build a custom theme system using Tailwind CSS and the OKLCH color space. The basics for this feature I extracted and is available on GitHub.

The approach I took generates an entire color palette from a single value, instead of managing eleven different color stops manually. Sounds complicated? It really is quite simple. Let me show you.

Tailwind allows defining custom colors using the @theme directive (these can then be used normally, e.g. text-brand-500 and bg-brand-50/60). Rather than hardcoding hex values, use CSS variables that change at runtime.

Here is the setup in app/assets/tailwind/application.css:

@import "tailwindcss";

@theme {
  --color-brand-50: oklch(0.99 0.01 var(--color-value));
  --color-brand-100: oklch(0.98 0.02 var(--color-value));
  --color-brand-200: oklch(0.94 0.04 var(--color-value));
  --color-brand-300: oklch(0.86 0.08 var(--color-value));
  --color-brand-400: oklch(0.74 0.14 var(--color-value));
  --color-brand-500: oklch(0.60 0.18 var(--color-value));
  --color-brand-600: oklch(0.52 0.16 var(--color-value));
  --color-brand-700: oklch(0.44 0.14 var(--color-value));
  --color-brand-800: oklch(0.36 0.12 var(--color-value));
  --color-brand-900: oklch(0.26 0.08 var(--color-value));
  --color-brand-950: oklch(0.16 0.04 var(--color-value));
}

Notice the same --color-value variable? By changing this one variable, all eleven shades update automatically. The lightness and chroma values stay consistent (for a harmonious palette). 🌈

Use these colors in your templates like any other Tailwind color:

<nav class="bg-brand-50 border-brand-100">
  <span class="text-brand-600">Custom Theme</span>
</nav>

OKLCH?

But wait… OKLCH? What is that? OKLCH is a modern color space that separates color into three components: lightness, chroma and hue. This makes it a perfect choice for generating color palettes (Tailwind CSS changed to OKLCH internally as well since v4, iirc).

Take the brand-500 color from the example above:

oklch(0.60 0.18 var(--color-value))

So:

• 0.60 is the lightness. A value of 0 is black, 1 is white. This color is medium brightness.
• 0.18 is the chroma (or color saturation). Higher values are more vibrant.
• var(--color-value) is the hue angle in degrees (0-360). This is what changes when you update the theme and defined initially in the style-element.

The beauty of OKLCH is that lightness and chroma remain constant across the palette. Only the hue changes. This means your brand color can shift from red to blue to green while maintaining the same visual weight and saturation at each shade level.

Setting up the HTML

In your layout, add a style tag with the default theme value:

<head>
  <style data-theme>
    :root { --color-value: 60; }
  </style>
  <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
  <%= javascript_importmap_tags %>
</head>

The default value of 60 is a sorta yellow-green hue. You can change it however you want.

Wiring up the theme controller

I just added this Stimulus controller for this demo (the client’s app worked a bit different).

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["value"]

  initialize() {
    this.style = document.querySelector('style[data-theme]')
  }

  update(event) {
    const value = event.target.value

    this.style.textContent = `:root { --color-value: ${value}; }`
    this.valueTarget.textContent = value
  }
}

The controller finds the existing style tag marked with data-theme and updates its content. This triggers a cascade: the CSS variable changes, all the brand colors are recalculated and the entire app recolors instantly. ✨

The demo interface

The example includes a simple slider to demonstrate the feature:

<div class="flex items-center gap-4 px-6 py-4 border-b border-brand-200" data-controller="theme">
  <span class="text-sm text-brand-700">Theme</span>
  <input type="range" min="0" max="360" value="60" data-action="theme#update" class="w-32 accent-brand-600">
  <span data-theme-target="value" class="text-sm text-brand-500">60</span>
</div>

<p class="mt-2 p-6 text-brand-900">Move the slider above to change the theme color.</p>

<ul class="flex gap-4 p-6">
  <li class="size-16 rounded-lg bg-brand-50 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-100 border border-brand-200"></li>
  <li class="size-16 rounded-lg bg-brand-200 border border-brand-200"></li>
  <!-- … all the way to brand-950 -->
</ul>

User-selected themes

While this approach was built for a white-label app, it works equally well for user-customizable themes.

The technique is flexible. You could extend it to store multiple theme variables: primary color, secondary color, accent color. Each would be a separate CSS variable that users can customize independently.

Pretty cool, right?

When working with inbound email in Rails using Action Mailbox, there’s a key requirement: managing EML files and blob storage. Once an email arrives at your domain, your email provider captures it and sends the data to you via webhook. You then extract what you need and process (or store) it. Action Mailbox requires: ActiveStorage ánd ActionMailer.

But what if you don’t have a need for ActiveStorage (including its cloud storage setup) or ActionMailer (because you use Courrier).

Most transactional email providers send their inbound emails as webhooks: Postmark, SendGrid, Mailgun and Mailpace. They all POST the email data to a webhook URL you configure.

Fuik is great at capturing just that: it captures those incoming webhooks, stores them in the database and calls your event class to process them. You see all your webhooks in at /webhooks. You can inspect and copy payloads, pull path accessors and generally debug what’s happening.

It is simple to get started:

bundle add fuik
bin/rails generate fuik:install
bin/rails db:migrate

That’s it. Your app now has /webhooks endpoints ready to receive any webhooks. Now to process inbound emails, let’s look at Postmark as an example (though every provider that sends inbound emails as webhooks wil work).

Postmark lets you receive inbound emails by pointing a MX record to their servers and then configure a webhook URL. When an email arrives, the data is POSTed to you. Let’s see how to process it in your app with Fuik.

Generate the class:

bin/rails generate fuik:provider postmark inbound_email

This creates three files.

Now open app/webhooks/postmark/inbound_email.rb. Postmark sends "To", "From", "Subject", "TextBody", and "HtmlBody". Route emails based on the recipient address:

module Postmark
  class InboundEmail < Base
    def process!
      return if to_email.blank?

      case to_email
      when /replies-.*@/
        message = Message.find_by(email_address: to_email)
        message.replies.create!(
          content: text_content,
          from: from_email
        )
      when /support@/
        SupportTicket.create!(
          from: from_email,
          subject: subject,
          body: text_content
        )
      end

      @webhook_event.processed!
    end

    private

    def to_email = payload["To"]

    def from_email = payload["From"]

    def subject = payload["Subject"]

    def text_content = payload["TextBody"]
  end
end

Postmark doesn’t send an event type in the payload (all inbound webhooks are inbound emails), so you set it statically. Use Fuik’s config (app/webhooks/postmark/config.yml) to extract it:

event_type:
  source: static
  value: inbound_email

Point your Postmark inbound webhook to https://yourdomain.com/webhooks/postmark in their dashboard, and emails start flowing in.

In the repo shared, I also added an example for Sendgrid to show another example how to do this.

Any provider with webhooks

Postmark and SendGrid are just examples. Mailgun, Brevo, Mailpace and others all send structured JSON via webhooks. The pattern is the same. Generate a provider, map the payload fields to your private methods, add your business logic and mark the event as processed.

Check out the example repository with both Postmark and SendGrid set up.

I hope to see more platform-independent Twitter-style feeds from others too. Web standards like RSS/Atom are great and don’t lock you into a platform or company. Just linear posts, no ragebaits or shitposting from others (and if so, unsubscribe).

With Perron’s customisable feeds feature, this is super easy to set up. I also created a tiny Raycast extension that makes posting super simple and quick too.

If you have a similar kind of feed, do share it below! 👇

Mine can be found at with here.

This article walks through building a drag-and-drop image upload custom element that works great in Rails forms. Starting with a simple avatar and ending with a reusable component that handles both inline and external forms. The code is, as usual, available on GitHub.

So first, why not use a regular file input or a Stimulus controller? The answer is that custom elements are perfect for self-contained components. They work anywhere in your HTML without needing to wire up data attributes or controller targets. Drop the tag in your view and it works. No configuration. No boilerplate.

With Stimulus you write:

<div data-controller="image-upload">
  <input type="file" data-image-upload-target="input" />

  <button data-action="click->image-upload#remove">Remove</button>
</div>

With the custom element I want to explore today, you write:

<image-upload name="user[avatar]" data-preview-image-url="...">
  <button type="button" data-remove-image>Remove</button>
</image-upload>

The component creates its own file input. It finds the form automatically. It handles drag-and-drop, preview rendering and removal. All wrapped in a clean, semantic HTML tag.

Lets get started, by creating the custom element in app/javascript/components/image-uploads.js:

class ImageUpload extends HTMLElement {
  #img = null;
  #input = null;

  connectedCallback() {
    this.#img = this.#image();
    this.#input = this.#fileInput();

    this.#load(this.#img);
    this.#dragAndDropListeners();
    this.#removeButtonListener();
    this.#clickToSelectListener();
  }
}

customElements.define('image-upload', ImageUpload);

The connectedCallback runs when the element is added to the page. It sets up the image element, creates the file input, loads any existing image and wires up all the event listeners.

The component creates an <img> tag if one does not already exist (only if the data-preview-image-url attribute is present):

#image() {
  if (!this.hasAttribute('data-preview-image-url')) return null;

  const img = document.createElement('img');
  this.insertBefore(img, this.firstChild);

  return img;
}

This means you do not need to add an <img> tag to your HTML. If you want to show an existing image, just add the data-preview-image-url attribute with the image URL.

Now it gets interesting. The component creates a hidden file input and appends it to the form, not to the component itself:

#fileInput() {
  const name = this.getAttribute('name');

  if (!name) {
    console.error('image-upload requires a "name" attribute');
    return null;
  }

  const input = document.createElement('input');
  input.type = 'file';
  input.name = name;
  input.accept = 'image/*';
  input.style.display = 'none';

  const formId = this.getAttribute('form');
  const form = formId ? document.getElementById(formId) : document.querySelector('form');

  if (form) {
    form.appendChild(input);
  } else {
    this.appendChild(input);
  }

  input.addEventListener('change', event => this.#fileSelected(event));

  return input;
}

This is crucial. The file input must be part of the form for Rails to receive it in the params. The component looks for a form in two ways: if a form attribute is present, it uses that ID to find the form. Otherwise, it finds the first form in the DOM. Use it inside a form (it finds the form automatically) or outside a form (pass the form ID via the form attribute).

When a file is selected (either via click or drag-and-drop), the component renders a preview:

#fileSelected(event) {
  const imageFile = event.target.files[0];

  if (imageFile) this.#process(imageFile);
}

#process(file) {
  if (this.#img) this.#render(file);
}

#render(file) {
  const reader = new FileReader();

  reader.onload = (event) => {
    this.#img.src = event.target.result;
  };

  reader.readAsDataURL(file);
}

The FileReader converts the file to a data URL which is displayed in the image element. The user sees the preview immediately.

The component listens for drag-and-drop events and adds a visual indicator:

#dragAndDropListeners() {
  this.addEventListener('dragover', event => this.#dragOver(event));
  this.addEventListener('dragleave', event => this.#dragLeave(event));
  this.addEventListener('drop', event => this.#drop(event));
}

#dragOver = (event) => {
  event.preventDefault();
  event.stopPropagation();

  this.setAttribute('data-drag-active', '');
}

#dragLeave = (event) => {
  event.preventDefault();
  event.stopPropagation();

  this.removeAttribute('data-drag-active');
}

#drop = (event) => {
  event.preventDefault();
  event.stopPropagation();

  this.removeAttribute('data-drag-active');

  const files = event.dataTransfer.files;
  const imageFile = Array.from(files).find(file => file.type.startsWith('image/'));

  if (imageFile) this.#process(imageFile);
}

When the user drags a file over the component, it sets a data-drag-active attribute. Style this with CSS to show visual feedback like a blue border or background color.

The component finds a button with data-remove-image and wires it up:

#removeButtonListener() {
  const removeButton = this.querySelector('[data-remove-image]');

  if (removeButton) removeButton.addEventListener('click', () => this.#remove());
}

#remove() {
  this.#input.value = '';

  if (this.#img) this.#img.removeAttribute('src');
}

When clicked, it clears the file input and removes the image preview. For has_one_attached in Rails, submitting an empty file input removes the attachment.

Using the component

Here is the avatar example inside a form:

<%= form_with(model: user) do |form| %>
  <div>
    <%= form.label :avatar, style: "display: block" %>
    <image-upload name="user[avatar]" data-preview-image-url="<%= url_for(@user.avatar) if @user.avatar.attached? %>">
      <button type="button" data-remove-image>Remove</button>
    </image-upload>
  </div>

  <div>
    <%= form.label :email_address, style: "display: block" %>
    <%= form.text_field :email_address %>
  </div>

  <div>
    <%= form.submit %>
  </div>
<% end %>

And here is the header example outside the form:

<image-upload name="user[header]" form="user_form" data-preview-image-url="<%= url_for(@user.header) if @user.header.attached? %>">
  <button type="button" data-remove-image>Remove</button>
</image-upload>

<%= form_with(model: user, id: "user_form") do |form| %>
  <!-- form fields -->
<% end %>

The form="user_form" attribute associates the component with the form by ID. The file input gets appended to that form and submits with it.

Custom elements work anywhere in your HTML without needing to wire up data attributes or controller targets. I’ve been enjoying custom elements more and more and for really contained examples like this one, or for static sites built with Perron I think they are wonderful tool to have.

This article builds directly on the previous setup, so make sure you have that in place before continuing (check out the repo for the full code base). The reposition logic is inspired by this article to create a Kanban board.

First, update the migration to include a unique index:

class AddPositionToQuestions < ActiveRecord::Migration[8.1]
  def change
    add_column :questions, :position, :integer, null: false
    add_index :questions, [:survey_id, :position], unique: true
  end
end

I like the positioning gem for this, make sure to set it up correctly.

Editing questions is really just vanilla Rails stuff, update the SurveysController with edit and update actions. It will save the question’s content alongside the survey models (I recently wrote how you can do this without using accepts_nested_attributes_for).

Now the more interesting part is the logic to reposition questions. Let’s go over the related parts. Add a RepositionController that stores the new position after drag-and-drop.

class RepositionController < ApplicationController
  def update
    resources.each_with_index do |resource, index|
      resource.update!(position: params[:new_position].to_i + index)
    end
  end

  private

  def resources
    resource_class.where(id: Array(params[:ids]))
  end

  def resource_class
    request.path.split("/")[1].singularize.classify.constantize
  end
end

Next is to updates your routes to include the new action:

Rails.application.routes.draw do
+  resources :questions, only: %w[destroy] do
+    collection do
+      patch :reposition, controller: "reposition", action: "update"
+    end
+  end
end

Update the nested-fields controller to support question removal.

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
+  remove(event) {
+    const field = event.target.closest("[data-sortable-id-value]");
+    const destroyInput = field.querySelector('input[name*="_destroy"]');

+    if (destroyInput) {
+      destroyInput.value = "1";

+      field.hidden = true;
+    } else {
+      field.remove();
+    }
+  }
}

The remove() method checks if there’s a _destroy hidden field (for existing records). If so, it sets the value to “1” and hides the field. For new records without this field, it simply removes the element from the DOM.

Sortable Stimulus controller

Create a new Stimulus controller (this is mostly copied verbatim from the Kanban board article I mentioned) for drag-and-drop functionality:

// app/javascript/controllers/sortable_controller.js
import { Controller } from "@hotwired/stimulus"
import { Sortable } from "sortablejs"
import { patch } from "@rails/request.js"

export default class extends Controller {
  static values = { endpoint: String };

  connect() {
    Sortable.create(this.element, {
      group: "questions",
      animation: 150,
      easing: "cubic-bezier(1, 0, 0, 1)",
      ghostClass: "opacity-50",
      selectedClass: "selected",
      onEnd: (event) => this.#updatePosition(event)
    });
  }

  async #updatePosition(event) {
    const items = event.items?.length > 0 ? event.items : [event.item];
    const ids = items.map(item => item.dataset.sortableIdValue);

    await patch(this.endpointValue, {
      body: JSON.stringify({
        ids: ids,
        new_position: event.newIndex + 1
      })
    });
  }
}

This controller uses SortableJS and @rails/request.js to enable drag-and-drop.

Update the edit view

Create the edit view (app/views/surveys/edit.html.erb):

<h1>Edit Survey</h1>

<%= form_with model: @survey, data: {controller: "nested-fields"} do |form| %>
  <div>
    <%= form.label :name %>

    <%= form.text_field :name %>
  </div>

  <ul data-nested-fields-target="fields" data-controller="sortable" data-sortable-endpoint-value="<%= reposition_questions_path %>">
    <%= form.fields_for :questions do |question_form| %>
      <li data-sortable-id-value="<%= question_form.object.id %>">
        <%= question_form.hidden_field :_destroy %>

        <%= question_form.label :content, "Question" %>
        <%= question_form.text_area :content %>

        <%= button_tag "Remove", type: :button, data: { action: "nested-fields#remove" } %>
      </li>
    <% end %>
  </ul>

  <div>
    <!-- … -->
  </div>
<% end %>

Key points in this view:

• The <ul> has both nested-fields and sortable controllers
• Each <li> has data-sortable-id-value for drag-and-drop tracking
• The _destroy hidden field marks questions for deletion
• The template includes the _destroy field for new questions too

And there you have it. A complete nested forms solutions for Rails with Stimulus that includes adding new questions, deleting and reposition them. From here it is straight-forward to add nested answers too!

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. 🚂

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.

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:

Before:

After taken from Perron’s docs; see logo:

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);
}

Before:

After:

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);
}

Before:

After:

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.

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. ⭐

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. 😅

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.

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.

A previous refactoring article from the book can be read here.

(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 twothree 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).

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. Like a 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.

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. 🥳

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.

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