Forem: matt swanson

Event sourcing for smooth brains: building a basic event-driven system in Rails

matt swanson — Sun, 21 Jul 2024 13:00:00 +0000

Event sourcing is a jargon filled mess that is unapproachable to many developers, often using five dollar words like “aggregate root” and “projections” to describe basic concepts.

While the high standards of “full event sourcing” might recommend building your entire application around the concept, it is often a good idea to start with a smaller, more focused area of your codebase.

I was familiar with the broadest strokes of event sourcing, but it always felt way overkill for me and something that involved a bunch of Java code and Kafka streams and all of the pain that comes with distributed, eventually consistent systems.

But lately I have been building with a very basic, dumbed down version of event sourcing (I call this “event sourcing for smooth brains”) and I can see how aspects of this model can be a great fit for a boring Rails monolith.

Why did I go down this path?

Your application is generating tons of events. Even if you don’t think about them as events, they are there. Imagine an Issue in a GitHub project: a new issue is created, a comment is added, a label is added, and so on.

It’s common to need to list these events in some kind of feed. And as the application becomes more complex, you’ll find that you need to do more and more “things” when an event happens.

Think back to the GitHub issue example: when a comment is added, you might need to email the person who created the issue, send a notification to a team member, update a counter, trigger an automated action, run a spam check, update the commenter’s contribution graph.

Pretty quickly you’ll be writing a bunch of code to handle all of these different things and having some standard patterns for interacting with events is going to be required.

I’ll describe the simple version we’ve been using for a while now at Arrows. We are not operating at the scale of GitHub or any other large application, but it has served us well and the patterns are simple enough that we can scale for a long time before we need to add more complexity.

It’s about the events

Instead of worrying about projections, aggregates, reactors, command query responsibility separation, and read models we’re just going to focus on the events.

We’re also going to focus on events around one specific domain: issues.

Create an issues_events table with this schema (adjust to your liking, but this is the basic structure I use):

create_table :issues_events do |t|
  t.references :issue, null: false, foreign_key: true

  t.references :actor, null: false, foreign_key: { to_table: :users }
  t.string :action, null: false, index: true
  t.references :record, polymorphic: true, null: true

  t.jsonb :extra, null: false, default: "{}"

  t.datetime :occurred_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
  t.timestamps
end

In a Rails app, I like making the event model under the Issues namespace, especially when you are using such a common name as “event”.

class Issues < ApplicationRecord
  belongs_to :project

  has_many :events, class_name: "Issues::Event"
end

class Issues::Event < ApplicationRecord
  belongs_to :issue

  belongs_to :actor, class_name: "User"
  belongs_to :record, polymorphic: true
end

The event model

The Issue::Event model is a simple model that stores the event data.

action: the name of the event (e.g. “comment_added”, “label_added”, etc). We put some validations on this to make sure we don’t have any typos or invalid events.
actor: the user that performed the action. We also have a “system” user for events that are generated by the application itself and not by a specific person
occurred_at: the time the event occurred
record: an optional polymorphic association to the record that was acted on (e.g. a Comment or a Label)
extra: a JSONB column for storing any extra data that might be needed. Generally be a bit weary of this because it will be unstructured, but for basic things it’s fine

class Issues::Event < ApplicationRecord
  belongs_to :issue

  belongs_to :actor, class_name: "User"
  belongs_to :record, polymorphic: true

  SUPPORTED_ACTIONS = %w[
    comment_added
    comment_deleted
    comment_viewed
    label_added
    ...
  ].freeze

  validates :action, inclusion: {
    in: SUPPORTED_ACTIONS,
    message: "%{value} is not a valid action"
  }
end

Nothing fancy here, just a basic Rails model that you can query and interact with just like any other model.

Now you’ll want a nice API to create these events. One thing we quickly found in practice is that some events would need to be throttled.

For example, if you want to track that a comment was viewed, you don’t necessarily need to record every single page view. You could group up the events within a certain time period into a single “comment viewed” event.

In our app, we wanted to be able to record events around lack of activity (e.g. this issue has not been viewed in a while) using a cron job but we didn’t want to keep adding no_activity events every time we checked so we set the throttle to be greater than the polling interval.

In “proper” event sourcing, you might record each of those events, then roll them up or create an intermediate snapshot or something fancier. For us, it was simple enough to do the throttling at creation time. We lose the full, unabridged history, but we don’t need to build other mechanisms to handle this.

class Issue < ApplicationRecord
  has_many :events, -> { order(occurred_at: :desc) },
    class_name: "Issues::Event",
    dependent: :destroy

  def record_event!(
    action,
    actor: Current.user,
    record: nil,
    extra: {},
    throttle_within: nil
  )
    if throttle_within.present?
      existing = events.find_by(
        action: action,
        record: record,
        actor: actor,
        occurred_at: throttle_within.ago..
      )
      return existing if existing&.touch(:occurred_at)
    end

    events.create!(
      action: action,
      record: record,
      actor: actor,
      extra: extra
    )
  end
end

# Recording events
@issue.record_event!(:comment_added, actor: @comment.author, record: @comment)

# Throttling events
@issue.record_event!(:comment_viewed, record: @comment, throttle_within: 15.minutes)

# Adding some extra data for extra bits of metadata
@issue.create_event(:label_added, extras: { name: @label.name })

We add a record_event! method to the Issue model that will create the event and optionally throttle it if it is within a certain time period.

To throttle, we look up an existing event for the same action, action, and record that occurred within the throttle time period and touch it to update the occurred_at timestamp.

Voila an activity feed!

So far, this is neat and all…but all we’ve done is create a glorified activity feed.

class Issues::FeedsController < ApplicationController
  def show
    @issue = Issue.find(params[:issue_id])
    @page, @events = pagy(@issue.events.order(occurred_at: :desc), items: 10)
  end
end

# Create a view or component to render each event in the feed
# For each item you have `action`, `actor`, `occurred_at`, and `record`
# to construct a line item. You can define icons for each type, different
# colors, etc (exercise left to the reader)
render Issues::UI::Feed.new(@events)

Now this is useful to have and will be easy to add more events to over time for sure. But it’s not really showing the power of event sourcing.

For that, we need to actually do other stuff with the events.

In my work at Arrows (and nearly every other Rails app I’ve worked on), you eventually will build up several different integrations, notification systems, and light “metric” dashboards that need to know when things happen in the app.

In the case of our Issue model, let’s say that when a comment is added, I need to send an email to the Issue creator, add it to the Issue creators GitHub notification inbox, and post it to a Slack channel.

Instead of reaching for heavier approaches like an Event Bus or a Pub/Sub library, we can use Rails after_create_commit callbacks to do this.

Gasp! A callback! Aren’t those evil? Well, no. You can certainly make a mess but callbacks are one of the powerful tools in Rails. It’s a sharp knife, which means “be careful with it”, not “ban it from the kitchen”.

class Issues::Event < ApplicationRecord
  # ...

  after_create_commit :broadcast

  private

  def broadcast
    Email::Inbox.new(self).process_later
    AppNotification::Inbox.new(self).process_later
    Slack::Inbox.new(self).process_later
    # Add whatever makes sense for your app
  end
end

The broadcast method is called after the event is created (note: it will be called the first time when an event is throttled, but not after that…this behavior may not be appropriate for all use cases).

We then send that event into a bunch of different objects that I like to call “inboxes”. Each inbox can determine: if the event should be sent, what data to send, and how to send it. By using the familiar Rails _later suffix, we hint that these should almost certainly be run as background jobs.

I won’t show the code for each inbox, but the general structure is something like this:

class Email::Inbox
  def initialize(event)
    @event = event
  end

  def process_later
    Job.perform_later(@event)
  end

  def process
    case @event.action.to_sym
    when :comment_added
      # Send an email to the issue creator
      # Send an email to any people subscribed to the issue
      # Send an email to any project maintainers with notifications enabled
      # ...
    when :label_added
      # ...
    when :comment_viewed
      # ...
    end
  end

  private

  class Job < ApplicationJob
    def perform(event)
      new(event).process
    end
  end
end

As you can imagine, some inboxes will handle a lot of different event types and some will only handle a few. But the general pattern is the same: create a class that receives the event and then processes it.

You can structure the inboxes however you want, including extracting classes to handle the events as the logic grows. This is especially nice for inboxes like a Slack integration where we can make objects like Slack::MessageBuilder that can handle converting an event object into the formatted API payloads that Slack expects.

As you add more functionality to your application, you’ll find that you have a clear and easy place to put the code to handle what to do when an event happens.

Reaping what you’ve sown

Now that you have the basics setup, features that seemed super complicated can become much more straightforward to build.

If you want to build a new integration to an external API, you have the seams to put it into place.

class Linear::Inbox
  #...

  def process
    return unless @event.issue.synced_to_linear?

    case @event.action.to_sym
    when :comment_added
      Linear::API.add_comment!(@event.issue, @event.record.body)
      #...
    end
  end

  # ...
end

If you want to build a basic workflow automation system, you have a great start.

class Issues::Workflow < ApplicationRecord
  belongs_to :issue
  has_many :conditions
  has_many :actions

  attribute :triggered_on
  validates :triggered_on, inclusion: {
    in: Issues::Event::SUPPORTED_ACTIONS
  }
end

@issue.workflows.create!(
  triggered_on: "comment_added",
  conditions: [
    { attribute: "created_at", operator: "lt", value: "2022-01-01" }
  ],
  actions: [
    { type: "reply", message: "This issue is stale, open a new one" }
  ]
)

If you want the ability to do basic “history” queries to see how often a feature is used, you’ve got a solid foundation.

Issue::Event.where(action: "comment_deleted")
  .where(issue: @account.issues)
  .count

If you need to “replay” events to backfill data, you can query the events like normal ActiveRecord models and do your own processing.

last_commented_at = @issue.events
  .where(action: "comment_added")
  .maximum(:occurred_at)
@issue.update(last_commented_at: last_commented_at)

This pattern has been powerful for us at Arrows. We’ve been able to quickly build out several “systems” with a small team. Our main domain object has around 50 different event types and we’ve found it very easy to work with over time.

Adding new features is a breeze and the code is easy to maintain. Because the event creation and processing are decoupled, it’s easy to test and we feel safe that we won’t breaking existing behaviors.

And lastly, because it is basic, simple code (instead of a full-blown event sourcing library or a bunch of extra services), it’s easy to understand and we actually use it.

Acknowledgements and further reading

The idea of event sourcing came back onto my radar after hearing about it from Daniel Coulbourne and Chris Morrellin the context of their Laravel package Verbs.

The always excellent Martin Fowler blog has a nice post on Event Sourcing that I found helpful in bridging the gap between how product engineers think and how the more academic aspects of event sourcing work.

And thanks to the Event Sourcing and CQRS books I read and yet did not understand at all back when I was slinging .NET and Java code early in my career. It didn’t click for me then, but glad to be able to take some parts of it now.

Writing better Action Mailers: Revisiting a core Rails concept

matt swanson — Mon, 16 Jan 2023 13:00:00 +0000

Mailers are a feature used in literally every Rails application. But they are often an after thought where we throw out the rules of well-written applications.

Writing mailers is a “set it and forget it” part of your codebase. But recently, I’ve revisited the handful of mailers in my application and I was shocked at both how bad things were and also how many nice mailer features in Rails I wasn’t aware of.

I’ve been writing Rails applications for over 10 years and there were things I figured out just this week about mailers that I will be using as my new defaults going forward.

Psst! If you like thinking about software and writing code in the "Boring Rails" style, we are hiring Product Engineers at Arrows. Come work with me!

Better display names

Rails has a built-in helper for formatting a display name that shows in email clients.

ActionMailer::Base.email_address_with_name("help@arrows.to", "Arrows HQ")
=> "Arrows HQ <help@arrows.to>"

ActionMailer::Base.email_address_with_name(user.email, user.display_name)
=> "Matt Swanson <matt@boringrails.com>"

This might seem trivial but it handles nil values and escaping quotes for you. And it’s a really nice touch for making emails from your app feel more polished.

I’ve written about this helper before but every time I mention it, someone replies telling them this is the first they’ve heard of it, so I will keep repeating it!

Changing the view folders

One thing that also bugs me is the file structure for mailer views. By default, the view for, e.g. NotificationMailer.welcome_email will be located at app/views/notification_mailer/welcome_email.html.erb.

This structure mirrors how controllers in Rails work. But it makes it difficult for you to see all your email templates at once. Often times, when we make a change to how we display emails, I need to scan all of the templates to make sure we aren’t doing anything funky.

I came across this post by Andy Croll that shows you how to put all your mailer views in one place. If you make one small tweak to your ApplicationMailer, you can achieve a more scannable folder structure.

class ApplicationMailer < ActionMailer::Base
  prepend_view_path "app/views/mailers"
end

Now you can put your mailer view in app/views/mailers/notification_mailer/welcome_email.html.erb. It is one extra level of folder nesting, but now you have a specific app/views/mailers folder instead of mixing in mailer views with controller views.

Multiple emails per mailer

Did you know you can put multiple emails inside of a single mailer?

There is nothing in the Rails documentation that says you can’t have multiple emails from one mailer, but it also isn’t explicitly encouraged. Sometimes you just need explicit permission from a random person on the internet and I am happy to be that person!

For whatever reason, every Rails app I’ve worked in has a one-to-one relationship between Mailer classes and email methods. Not only does this make it harder to grok the emails in your system, but it presents weird friction in naming that should jump out as a code smell.

Previously, I would make mailers like:

class CommentReplyMailer < ApplicationMailer
  layout "minimal"

  def comment_reply_email(user, comment)
    # mail(to: ...)
  end
end

class UserMentionedMailer < ApplicationMailer
  layout "minimal"

  def mentioned_email(mentionee, comment)
    # mail(to: ...)
  end
end

Why? I don’t really know. I can’t defend separating them.

Instead, you can group functionality into one mailer.

class NotificationMailer < ApplicationMailer
  layout "minimal"

  def comment_reply(user, comment)
    # mail(to: ...)
  end

  def mentioned(mentionee, comment)
    # mail(to: ...)
  end
end

Now you can see all the notifications in one file. There are so many times when I forget that we have a certain email going out and it doesn’t get updated when a new feature is added to the app.

You don’t need to write the word “email”

Mailers send emails. You don’t need to append _email to your methods/views – especially if you follow the above tip to put the views into app/views/mailers.

# No one is going to be surprised that this code sends an email
NotificationMailer.comment_reply_email(@user, @comment).deliver_later

# So don't prefix everything with `email`!
NotificationMailer.comment_reply(@user, @comment).deliver_later

Parameterized mailers

Okay, so far all of these tips are neat but nothing too wild.

Recently, I’ve been building a feature that allows you to send transactional from your own sending domain. So instead of getting a system email from hello@arrows.to, it would come from onboarding@acme-saas.com. There is some DNS related stuff that needs to happen in the background but I want to focus on the mailer portion of this feature.

One difficulty was making sure that, if an account had setup the custom sending domain, we overwrite the From address in the mailer. The problem was that there are many mailers in the application and I didn’t want to put this conditional code in every mailer. I was worried that – down the line – I would add a new email and then forget to consider the case where the account is using a custom sending domain.

I started with this basic implementation in one of the impacted mailers.

class NotificationMailer < ApplicationMailer
  def comment_reply(user, comment)
    # ...
    mail(
      to: user.email,
      from: build_from_address(comment.account)
    )
  end

  private

  def build_from_address(account)
    if account.custom_email_sender?
      email_address_with_name(
        account.custom_email_address,
        account.custom_email_name
      )
    else
      email_address_with_name("hello@arrows.to", account.name)
    end
  end
end

My first thought was that I could add some code to my ApplicationMailer to check the Current.account. But I hit a snag because mailers should be sent in a background job (via deliver_later) and we lose the context of the current request (and thus, the Current attributes). There are ways around this – like a middleware to pass along the Current attributes to the job – but something felt off to me.

When looking for a better way to implement this, I went back to the Action Mailer documentation and I noticed something: none of the example code was passing in data to the mailer methods directly. Instead there were accessing everything via params.

So instead of:

NotificationMailer
  .comment_reply(user, comment)
  .deliver_later

You would write:

NotificationMailer
  .with(user: user, comment: comment)
  .comment_reply
  .deliver_later

I had never used this pattern before. Mailers have not changed since I first learned Rails (in the 2.x days!) but in Rails 5.1, the concept of a “parameterized” mailer was introduced.

My first impression was that I didn’t quite understand the point of this. I generally prefer having the explicit method arguments on the mailer method compared to a generic params hash.

But, this time it finally clicked!

The extra benefit of using with and parameterized mailers is that you can add before_action callbacks to your mailers to configure options like the custom sending domain outside of the context of the mailer method.

I used this concept to make a small change:

class NotificationMailer < ApplicationMailer
  before_action { @account = params[:account] }
  before_action { @from = build_from_address }

  def comment_reply(user, comment)
    # ...
    mail(to: user.email, subject: "New reply", from: @from)
  end

  def mentioned(mentionee, comment)
    # ...
    mail(to: mentionee.email, subject: "You were mentioned", from: @from)
  end

  private

  def build_from_address
    if @account.custom_email_sender?
      email_address_with_name(
        @account.custom_email_address,
        @account.custom_email_name
      )
    else
      email_address_with_name("hello@arrows.to", @account.name)
    end
  end
end

So far, this isn’t really much better but this is setting the stage for being able to pull this configuration out of each mailer.

Dynamic defaults

The next piece of the puzzle is making use of mailer default options. One thing you might not realize (because I didn’t either…) is that you can pass a lambda to default to set the value dynamically.

class NotificationMailer < ApplicationMailer
  # You can pass in a static value
  default from: "hello@arrows.to"

  # But...it's probably more useful to use dynamic values
  default from: -> { build_default_from_address }

  private

  def build_default_from_address
    # Construct the default from address here
  end
end

The nice part about using default is that individual mailers can override the from option if they need to, but if you set the default, you can omit it completely.

The key breakthrough for my implementation of the custom sending domain feature comes from combining the dynamic defaults with the parameterized mailer option for passing in data.

Connecting the dots

By using dynamic defaults and before_action callbacks, you can have access to the params hash when configuring the defaults.

class NotificationMailer < ApplicationMailer
  default from: -> { build_default_from_address }

  before_action { @account = params[:account] }

  def comment_reply(user, comment)
    # ...
    mail(to: user.email, subject: "New reply")
  end

  def mentioned(mentionee, comment)
    # ...
    mail(to: mentionee.email, subject: "You were mentioned")
  end

  private

  def build_from_address
    if @account.custom_email_sender?
      email_address_with_name(
        @account.custom_email_address,
        @account.custom_email_name
      )
    else
      email_address_with_name("hello@arrows.to", @account.name)
    end
  end
end

NotificationMailer.with(account: @account).comment_reply(@user, @comment).deliver_later

Now the logic for the custom sending address has been completely removed from the mailer methods. And it now clear that this behavior is not specific to just the NotificationMailer. Since we pulled the code into callbacks and parameterized options, we can hoist it up to a new mailer base class.

This also allows me to introduce the concept of an “Account scoped email” – an email sent in the context of a specific Account, which may have additional configuration or features.

class AccountMailer < ApplicationMailer
  layout "minimal"
  default from: -> { build_default_from_address }

  before_action { @account = params.fetch(:account) }

  private

  def build_from_address
    if @account.custom_email_sender?
      email_address_with_name(
        @account.custom_email_address,
        @account.custom_email_name
      )
    else
      email_address_with_name("hello@arrows.to", @account.name)
    end
  end
end

class NotificationMailer < AccountMailer
  # ...
end

class DigestMailer < AccountMailer
  # ...
end

class ParticipationMailer < AccountMailer
  # ...
end

There is one subtle change that also improves the developer experience and ensures that future mailers don’t omit the with(account: @account) configuration.

class AccountMailer < ApplicationMailer
  # ...

  before_action { @account = params.fetch(:account) }
end

The before_action will fail with a NoMethodError if the params are omitted and by using fetch it will fail with KeyError: :account if the caller does not pass in the account.

Wrap it up

Mailers are the worst part of a Rails application in terms of quality. While the framework provides an extremely powerful and elegant conceptual compression around sending emails, we often write them once and never touch them in our application code.

We frequently ignore complex code and duplication in mailers because they are at the edge of the system. The difficulty in rendering HTML email views does not help and further encourages “get it working and never touch it again” behavior.

But you the tools for organizing mailers just like the rest of your codebase.

I hadn’t brushed up mailers since I first learned Rails and I was surprised by how much I could improve them with a couple of small changes.

In my specific case, I was able to abstract a cross-cutting behavior (customizing the sender address) into a base mailer class. By using dynamic defaults and parameterized mailers, I can provide a pleasant developer experience that makes it easy to do “the right thing” for future code.

By applying some extra thought on naming and folder structure, I was able to make the mailer methods read better and make it easier to see the full scope of email views in the app. And by grouping multiple emails into single mailer classes, you can keep things that are similar close together in the code.

As I move forward, I will be working to define more application specific mailer contexts: for example an AccountMailer base class for emails generated within the scope of an account and SystemMailer base class for things like login and password reset emails that have different configuration options.

Your mailers can be an exemplary part of your codebase with a little bit of work!

Thinking in Hotwire: Progressive Enhancement

matt swanson — Tue, 16 Aug 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

There are many tutorials about how to get started with Hotwire and how to use the individual pieces. But one thing that took me a while to grasp was how to “think in Hotwire”.

Hotwire itself is an overarching concept (HTML-over-the-wire) and you’ll need to know when to use the different pieces (Turbo Drive, Frames, Streams, Stimulus, Turbo Native, Strada).

Because Hotwire is a collection of tools, you can solve problems multiple ways. There are features you can build with Frames that you could also build with Streams. You can always drop to a “lower level” tool and make something work.

So how should you know when to reach for each tool?

I think the best approach comes from the earliest days of web development: progressive enhancement.

Scaffolds and CRUD without Hotwire

Let’s start with the absolute bare bones: the pre-Hotwire days of Rails. You would scaffold out a resource-based controller.

To add a comment to a post, you would have a comments_controller with a new action to render a form.

You would submit a new comment to comments#create where the comment model would be saved and then we send a redirect back to the post#show route.

It’s as boring as you can get, but it works and is the foundation upon which RESTful web applications were built.

Adding Turbo Drive

So what if we wanted to enhance the experience just the tiniest amount? We could the first layer of Hotwire: Turbo Drive. If you’re on a recent version of Rails, Turbo Drive is on by default, even if you didn’t realize it.

Now when you click + Add, instead of a full-page reload of comments#new, we use Turbo Drive to fetch the page via AJAX and then Turbo Drive swaps out the <body> contents. This behavior (originally called Turbolinks) mimics the responsiveness of a single-page application, but everything is still server-rendered in Rails.

Turbo Drive does the same thing when you submit the comment form: instead of a full page reload, the <body> is swapped, even when we do a redirect. The JS and Rails portions of Turbo Drive work together to make this seamless (…assuming you follow the right conventions!).

So you could stop right here and technically you are using Hotwire. Turbo Drive is mostly invisible for Rails developers. If you don’t need any more interactivity, you don’t need to go any deeper.

Adding Turbo Frames

While Turbo Drive originated as Turbolinks, Turbo Frames are a new concept in Hotwire. I’ve described Turbo Frames before as “iFrames but they work how you would want them to”. In Hotwire, Turbo Frames are used for partial page updates.

A Frame works similar to Turbo Drive: navigation visits and form submissions are intercepted, made via AJAX, and then the response is swapped into the page. But with Frames, instead of swapping the whole <body> tag, only the contents of a matching Turbo Frame is swapped.

So if you have a link instead a Turbo Frame with an id of comment_123, Hotwire will look for a matching <turbo-frame id='comment_123'> tag in the response to swap.

The canonical use-case is inline editing. If you have a list of comments and you wrap a frame around each comment, you can add a edit button. Clicking the edit button can render a comments#edit response, but swap out the form with the frame instead of loading a separate page.

Adding Turbo Streams

Turbo Drive replaces the whole <body> tag. Turbo Frames replace a frame. Turbo Streams go even more granular.

Turbo Streams provide a set of standard operations for manipulating the HTML on the page. You can add, remove, or replace content.

In our comment example, if you want to delete a comment, you can respond to the request with a Turbo Stream to remove the comment from the page. Or if you create a comment, you can add it to the end of the list.

Turbo Streams are the Hotwire version of another classic Rails technique: server-generated JavaScript response (SJR). In the past, you could return back a snippet of JavaScript that would get executed in the page. But this caused issues with Content Security Policies and was a bit too permissive.

Turbo Streams provides a CRUD-like abstraction to handle nearly anything you should have been doing with SJR.

Adding Turbo Streams + Action Cable

Turbo Stream responses can also be broadcast out-of-band using Action Cable. One major point of confusion is that Turbo Streams do not have to be sent over Action Cable or web sockets, you can use them within a normal HTTP request/response cycle.

But let’s say we want real-time functionality so that when someone else adds a comment, it gets added to our view of the page without doing a refresh.

Adding Stimulus

Hotwire guides you to write as much of your application using server rendered Ruby code as possible. But there are cases where you still want extra sprinkles of JavaScript functionality on the client side.

Stimulus is the recommended JavaScript framework for attaching functions to your HTML markup and responding to simple browser events.

One thing to note is that Stimulus does not provide anything to support client side rendering. There are no templates or JSX. If you find yourself generating a lot of HTML in your Stimulus controllers, you should take a step back and re-assess.

Stimulus controllers are often general-purpose and under 50 lines of code.

If you want to support collapsing comments, you could add a simple Stimulus controller to show or expand a comment. (Note: in this specific case, a Hotwire enthusiast might reach for native HTML elements like <detail> but I digress…)

Adding custom components / React / client side JavaScript

There is a time and place for tools like React for high interactivity components. Whether you use a tool like React, Vue or Web Components, there are things that are best built on the client side that go beyond what Stimulus can handle.

For this, you can add a small, isolated component to the page. An example from Rails is the Trix rich text editor: it is a standard <trix-editor> web component.

In our comment example, maybe you want to add an emoji picker or some kind of fancy drag and drop file uploader. You might wrap these richer JavaScript libraries in a Stimulus controller to help manage Turbo lifecycle events.

Hotwire advocates don’t say that you should never write JavaScript components, but rather that you should start with the other tools and only reach for this level when you really need it.

Adding Turbo Native

Once you’ve built a feature in your web application, you can use the Turbo Native iOS and Android adapters to create mobile applications that wrap display your same app content inside of a web view.

This is not a “mobile optimized web app” but a real Swift or Kotlin app that renders pages from your Rails app.

There are some conveniences to create native action bars and buttons.

The main idea is to re-use as much of your Rails views as possible and then Turbo Native provides a mechanism to eject and write some screens in the platform native languages. Again, it’s the idea of progressive enhancement.

The flagship example app (the Hey email client) for instance has a fully native inbox screen, but many of the secondary or account setting screens are wrappers around Rails views.

The Turbo Native functionality should still be considered as a beta release. Most developers writing Hotwire applications are not using the native features, but it is nice to know that some folks are laying the groundwork for this style of development.

Adding Strada

The last piece of Hotwire is the [as of summer 2022] unreleased Strada library. This is an extension of the Turbo Native functionality and helps bridge the gap when you need to communicate between the Swift or Kotlin parts of your application and the HTML/Rails portions.

This library will be a convenience extension to Turbo Native, it doesn’t add anything fundamentally new to the mix.

Until the project is actually released, it’s fine to ignore.

Wrap it up

Hotwire builds on the idea of progressive enhancement. You should use the least amount of the tooling as possible to achieve your desired outcome. As you move “down the stack” of what Hotwire offers, you trade off more power for more complexity.

The nice part about this approach is that you can build versions of features quickly, test and iterate based on feedback, and then layer on more real-time and interactive functionality as needed.

The progressive enhancement approach pairs beautifully with HTML and Hotwire encourages you to explore what can be done with native browser elements and only layers on extra tooling to complement or upgrade the platform.

Hotwire as a brand is an umbrella for several different tools and hopefully this overview will help you know how far down to reach and how the individual tools come together to build a cohesive and compelling stack.

Galaxy brain CSS tricks with Hotwire and Rails

matt swanson — Tue, 26 Jul 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

In Hotwire applications, you need to lean more on the fundamentals of CSS and HTML. If you’re like me, you probably learned just enough CSS to get by, but never reach for it first. But that’s changed recently and I wanted to share patterns I’ve picked up recently that improve my Rails apps.

Empty States and Turbo Streams

An extremely common pattern in Rails apps is rendering a collection of elements and if the collection is empty, render an empty state.

<div id="my_list" class="flex flex-col divide-y">
  <% if @list.size > 0 %>
    <%= render partial: "list_item", collection: @list %>
  <% else %>
    <p>
      Whoops! you have no items!
    </p>
  <% end %>
</div>

This works fine when rendering a typical page, but if you use Turbo Streams to add or remove list items, you’ll find a problem.

If you had two items in the list, and you remove both via Turbo Streams, the container will be empty but you won’t have rendered the empty state. And if the list is empty and you dynamically append an item, you’ll want to remove the empty state.

You could re-render the whole list instead of inserting items, but one technique that I’ve found helpful is using the CSS only-child pseudo-selector.

I’ll show examples with Tailwind (because Tailwind is really, really good), but the same concept applies in regular CSS.

The idea is to always render the empty state and then use CSS to only show it if there are no items.

<div id="my_list" class="flex flex-col divide-y">
  <p class="only:block hidden">Whoops! you have no items!</p>
  <%= render partial: "list_item", collection: @list %>
</div>

Using Tailwind’s only modifier we set the empty state to have display block if it is the only child of the container, otherwise hide it.

Now you can stream back operations to append or remove items to the my_list container and let CSS handle hiding or showing the loading state.

Note: you may want to use last-child, first-of-type, or some other modifier depending on your specific markup. Give it a shot!

Tailwind Variants with Data Attributes

Hotwire, especially Stimulus, makes use of HTML data attributes heavily. One neat trick is using data attributes to reduce conditionals in views.

Let’s say you have a list of comments and only admins can delete the comments.

<%= tag.div id: dom_id(@comment) do %>
  <p><%= @comment.body %></p>

  <% if Current.user.admin? %>
    <%= button_to "Delete", @comment, method: :delete %>
  <% end %>
<% end %>

You could instead use a data attribute on the <body> of your page to conditionally show admin-related things.

<body <%= 'data-admin' if Current.user.admin? %>>
  ...
</body>

And then write styles based on that attribute. Tailwind makes it easy to add custom variants for this via the plugins section of the Tailwind config file:

plugins: [
  function({addVariant}) {
    addVariant('admin', 'body[data-admin] &')
  }
],

With this config change you can now use admin: with any Tailwind classes.

<%= tag.div id: dom_id(@comment) do %>
  <p><%= @comment.body %></p>

  <div class="admin:block hidden">
    <%= button_to "Delete", @comment, method: :delete %>
  </div>
<% end %>

But wait? Isn’t this super risky because someone could just fiddle with the HTML and delete a comment? Well, yes, they could – but you need to be checking authorization on the server-side anyways. It’s a trade-off but there are cases where this cleans up a ton of conditional view logic.

Shout-out to my friend Marc Kohlbrugge for sharing the idea on Twitter!

In our app we recently used this technique to change how much margin we needed on an element based on user roles. Certain roles have a fixed height header that we needed to account for. Instead of a bunch of conditionals, all we had to end up writing was viewer:top-0 editor:top-12.

Dynamic styles with erb

Don’t forget that you can use generate <style> tags dynamically!

<style>
  [data-user~="<%= Current.user.id %>"] {
    background: yellow;
  }
</style>

<div>
  <p><%= @comment.body %></p>
  <%= tag.span data: { user: @comment.author.id } do %>
    <%= @comment.author.name %>
  <% end %>
</div>

You could use a little CSS to highlight comments that you made with a yellow background by targeting a data-user attribute.

This is actually an old Rails technique from Basecamp that was popular because it works really well with fragment caching. You can cache the same chunk of HTML and then use CSS to change the styles instead of needing multiple, slightly different cache entries.

I’ve also used this concept for building custom theming features by taking advantage of CSS variables.

<style>
  :root {
    --color-brand: <%= @account.brand_color %>;
    --color-brand-contrast: <%= ColorHelper.contrast(@account.brand_color)) %>;
    --color-brand-tint: <%= ColorHelper.tint(@account.brand_color) %>;
  }
</style>

You can use this to define custom Tailwind colors:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: 'rgb(var(--color-brand) / <alpha-value>)',
        'brand-contrast': 'rgb(var(--color-brand-contrast) / <alpha-value>)',
        'brand-tint': 'var(--color-brand-tint)'
      }
    }
  }
}

And now you can use bg-brand or text-brand-contrast in your application.

Stop string interpolating class names!

You will be writing a lot more HTML markup in Hotwire apps: more views, more partials, more components. Make sure you are taking advantage of newer Rails features for generating HTML without doing a bunch of gross string interpolation.

If you’re writing markup like this:

<li class="bg-gray-50 p-2 text-gray-700 <%= 'line-through' if @task.completed? %>">
  <%= @task.name %>
</li>

Please stop! It’s hard to read and tricky to match all of the closing punctuation. There are better ways!

<%= tag.li class: ["bg-gray-50 p-2 text-gray-700", "line-through": @task.completed?] do %>
  <%= @task.name %>
<% end %>

Rails 6.1 added a class_names helper method and the tag builder will automatically use it for conditionally setting class values. It’s awesome!

It’s extra powerful when using a library like ViewComponent where you have a lot of conditional styles, or just want to group up utility classes in a more organized manner.

class MyWidget < ViewComponent::Base
  ...

  def container_classes
    [
      "flex items-center justify-center space-x-2 rounded-full",
      "disabled:pointer-events-none disabled:select-none",
      "font-medium tracking-wide",
      {"text-white bg-black hover:bg-neutral-900": variant == :primary},
      {"text-neutral-600 border hover:bg-neutral-50 hover:text-neutral-900": variant == :secondary},
      {"text-neutral-600 hover:text-neutral-900 hover:bg-neutral-50": variant == :tertiary},
      {"w-full": full_width?}
    ]
  end
end

Wrap it up

CSS is often one of the last tools Rails developers reach for when trying to solve a tricky problem. We are much more inclined to add conditionals to views or fall back to string interpolation to “make it work”. But there are a few techniques that can make working with CSS in your Rails app improve the readability and durability of your code.

Even though Hotwire’s servered rendered approach feels retro, remember that we don’t have to use CSS like it’s 1998 anymore!

Adding keyboard shortcuts and hotkeys to StimulusJS

matt swanson — Mon, 11 Jul 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

Keyboard shortcuts are a great way to level up your user experience and improve the accessibility of your web applications. Even if you aren’t ready for advanced hotkey schemes, small things like binding the Escape key to close a modal can have a big impact.

Stimulus doesn’t come with built-in support for hotkeys. As part of a recent project at Arrows, I evaluated the ecosystem and wanted to share my thoughts.

stimulus-hotkeys

This package provides a hotkeys controller and uses a JSON object to map keyboard shortcuts into Stimulus actions.

<div
  data-controller="hotkeys"
  data-hotkeys-bindings-value='{"ctrl+z, command+z": "#foo->editor#undo"}'
></div>

<div id="foo" data-controller="editor"></div>

The syntax of the bindings map is similar to the Stimulus action syntax, with the addition of a preceding selector to find the Stimulus controller to invoke the action on. Internally, stimulus-hotkeys uses the more general HotKeys.JS library so it supports all kinds of fancy combinations, modifiers, and scopes.

I liked that the shortcut mapping exists in the HTML markup; this felt very much in the spirit of Hotwire. This library adds no extra code to your Stimulus controllers, which is ideal if you are combining together other third-party controllers.

Unfortunately, adding a hash-like data structure as an HTML attribute is tricky and I don’t love the JSON syntax.

stimulus-use/useHotkeys

The stimulus-use project is a collection of reusable behaviors for Stimulus. If you are familiar with React, this project is similar to React’s hooks system, but for Stimulus controllers.

Included in this collection is useHotkeys. As with stimulus-hotkeys, the heavy lifting is done by HotKeys.JS.

Here you need to define the hotkeys and respective handlers inside of your own Stimulus controllers:

import { Controller } from '@hotwired/stimulus'
import { useHotkeys } from 'stimulus-use'

export default class extends Controller {
  connect() {
    useHotkeys(this, {
      'cmd+t': [this.openPalette],
      '.': [this.editFile]
    })
  }
}

This library felt right at home in a Stimulus controller and it handles unregistering the shortcuts when a controller is disconnected automatically. It was super clear what hotkeys were configured and this felt like a great option for adding hotkeys to your own application controllers.

One downside that was specific to our needs was that I had a controller that was always be on the page, but should not respond to hotkeys when hidden. While useHotkeys handles the Stimulus controller lifecycle, it does make it inflexible when it comes to binding and unbinding the keyboard events.

HotKeys.JS (directly)

After exploring the two most popular Stimulus-specific solutions and realizing they both used the same underlying dependency, I decided to go straight to the source.

import { Controller } from '@hotwired/stimulus'
import hotkeys from 'hotkeys-js'

export default class extends Controller {
  connect() {
    hotkeys("esc", () => this.doSomething())
  }

  disconnect() {
    hotkeys.unbind("esc")
  }
}

Adding the library directly is straightforward. You do need to be careful to clean up your event listeners by calling unbind or else you’ll end up with multiple instances of the hotkey functions getting created.

For very simple cases (one or two basic hotkeys), this approach is perfectly valid. In our application, I ended up going this route as I needed more fine-grained control of when the shortcuts were bound/unbound.

github/hotkey

The last option I evaluated was a small library from GitHub called github/hotkey. It is not Stimulus / Hotwire specific.

<button data-hotkey="Shift+?">Show help dialog</button>

<a href="/page/2" data-hotkey="j">Next</a>
<a href="/help" data-hotkey="Control+h">Help</a>
<a href="/rails/rails" data-hotkey="g c">Code</a>
<a href="/search" data-hotkey="s,/">Search</a>

I found this library via the sourcemaps of HEY.com and it has been battle-tested by GitHub in the main Rails app (from the README: “This is used on almost every page on GitHub.”).

The data-hotkey attribute has the cleanest syntax of any of the options. You would want a wrapper Stimulus controller to handle lifecycle events, but it would be only for calling install and uninstall.

The design of this library relies more heavily on browser default behaviors. Instead of calling arbitrary JavaScript functions (or Stimulus actions), github/hotkey triggers the action on the target HTML element: links would trigger a navigation visit, buttons would get submitted, input fields would get focus, etc.

If you can structure your markup to use native browser functionality, this is a great option. But there isn’t a way to hook into your existing Stimulus actions directly.

Wrap it up

It really depends on what your specific hotkey needs are:

stimulus-hotkeys is a drop-in tool that doesn’t require any extra JavaScript
stimulus-use/useHotKeys is a convenient Stimulus-native API wrapper around HotKey.js
HotKey.js is a powerful abstraction around key events that you can mix into your own code
github/hotkey leans heavily on native browser behavior and has the nicest syntax

Ultimately, you’ll need to navigate the trade-offs for what you’re trying to build. In my case, I went with directly using HotKey.js because it best fit my specific requirements.

The most underrated Rails helper: dom_id

matt swanson — Tue, 28 Jun 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

The dom_id helper in Rails is over a decade old, but has proven to be an invaluable concept in Hotwire.

This secret workhorse powers all kinds of HTML-related behavior in Rails. It has one key job: making it easy to associate application data with DOM elements.

dom_id takes two arguments: a record and an optional prefix.

The record can be anything that responds to to_key and model_name, but 99% of the time you are passing it an ActiveRecord model. The prefix can be anything that responds to to_s, but 99% of the time it is a symbol.

From the docs:

dom_id(Post.find(45)) # => "post_45"
dom_id(Post.new) # => "new_post"

dom_id(Post.find(45), :edit) # => "edit_post_45"
dom_id(Post.new, :custom) # => "custom_post"

The reason this helper is so nice is that it sets a convention. Instead of defining your own way of identifying markup and later hoping you remember the pattern, Rails provides a standard; you don’t need to switch contexts to know if you set an id to “post_23_comments” or “comments-post-23” or wait, was it “post_23-comments”?

By providing stable id values for your elements, you avoid fragile code like targeting the first element child or finding a node based on the text value.

Here are places where you should regularly reach for dom_id when building Hotwire apps.

Super clean tag builders

Leaning into HTML markup as the source of truth means adding extra attributes and conditionals when rendering templates. While you can do plain old string interpolation in your ERB templates, Rails has a set of nice tag builders that help you avoid drowning in a sea of brackets, braces, and octothorpes.

<%= tag.div id: dom_id(@post, :comments), class: "flex flex-col divide-y" do %>
  <%= render @post.comments %>
<% end %>

As you use these helpers more, make sure you check out these tips:

Set up the Tailwind Intellisense plugin for VS Code to autocomplete when using tag helpers
Take advantage of class_name helper (from the classNames React API) for conditional classes
For commmon elements, consider extracting a component with a lightweight helper or a library like ViewComponent

Deep linking anchor tags

Since Rails leans so heavily on native browser features, make sure you take advantage of anchor tags on links. You can use dom_id to scroll the browser directly to an element with the corresponding id (or generate a permalink that users can share).

<%= link_to "View comment", posts_path(@post, anchor: dom_id(@comment)) %>

You can also use this pattern for redirects. For example, after creating an item in a list, you can redirect back to the index page but scroll to the new item.

class CommentsController < ApplicationController
  def create
    @post.comments.create!(comment_params)

    redirect_to posts_path(@post, anchor: dom_id(@comment))
  end
end

A few more tips related to deep linking:

You can use the :target pseudo-class to style the element with an ID matching the URL anchor. In Tailwind, simply use the target prefix (e.g. target:bg-yellow-50 to add a subtle yellow background to an element when it matches the URL anchor)
Another handy CSS property is scroll-margin-top: the browser will scroll the targeted element all the way to the top of the window. You may want a little extra padding, but only when you scrolled to the element. Don’t add extra margin or padding to your designs or add weird wrapper divs…scroll-margin-top (Tailwind class: scroll-mt) is the answer.

With Turbo Frames

When you start adding Turbo Frames to your application, you’ll need to provide an id for the frame tag. The Rails turbo_frame_tag uses – you guessed it – dom_id under the hood. But you can also pass in your own ids as well.

turbo_frame_tag @post # => <turbo-frame id="post_123"></turbo-frame>
turbo_frame_tag dom_id(@post, :comments) # => <turbo-frame id="comments_post_123"></turbo-frame>

Since a Turbo Frame needs to be unique per page, dom_id is a convenient way to generate frame ids, especially if you have multiple frames on the page.

And since you can navigate a frame via other links, it’s a great convention to follow:

<%= turbo_frame_tag @comment, src: comment_path(@comment) %>

<!-- Elsewhere... -->
<%= link_to "Edit", edit_comment_path(@comment), data: { turbo_frame: @comment } %>

Scoping Turbo Stream responses

Making small mutations on a page with Turbo Streams is super powerful, but since your stream actions are in a separate turbo_stream.erb file, it can be tricky to match up your ids between views.

Once again, dom_id keeps things consistent.

<!-- app/views/plans/quick_edit/update.turbo_stream.erb -->
<%= turbo_stream.replace dom_id(@plan, :title), partial: "plans/title" %>
<%= turbo_stream.replace dom_id(@plan, :notes), partial: "plans/notes" %>
<%= turbo_stream.replace dom_id(@plan, :assigned), partial: "plans/assigned" %>

And by adding the correct ids to your markup, the Turbo Stream responses are super clean:

<!-- app/views/comments/destroy.turbo_stream.erb -->
<!-- Calls `dom_id(@comment)` under the hood -->
<%= turbo_stream.remove @comment %>

Wrap it up

Who would have thought that a simple helper to generate HTML id values from your application models would be such a useful concept that, more than a decade after first being introduced, it continues to prove helpful even on the newest and shiniest parts of Rails.

If you haven’t been using dom_id before, consider it the next time you write a view in your Rails app. You might be surprised at how much more pleasant it is to create HTML when you aren’t littering it with code like:

<div id='<%= "#{@post.id}-comments" %>'>
</div>

Self-destructing StimulusJS controllers

matt swanson — Mon, 13 Jun 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

Sometimes you need a little sprinkle of JavaScript to make a tiny UX improvement. In the olden days, full-stack developers would often drop small jQuery snippets straight into the page:

<script type="application/javascript">
  $(".flash-container").delay(5000).fadeOut()
  $(".items").last().highlight()
</script>

It got the job done, but it wasn’t the best.

In Hotwire apps you can use a “self-destructing” Stimulus controller to achieve the same result.

Self-destructing?

Self-destructing Stimulus controllers run a bit of code and then remove themselves from the DOM by calling this.element.remove().

Let’s see an example:

// app/javascript/controllers/scroll_to_controller.js
import { Controller } from '@hotwired/stimulus'

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

  connect() {
    this.targetElement.scrollIntoView()
    this.element.remove()
  }

  get targetElement() {
    return document.getElementById(this.locationValue)
  }
}

This controller takes in a location value and then scrolls the page to show that element.

<template
  data-controller="scroll-to"
  data-scroll-to-location-value="task_12345"></template>

For self-destructing controllers, I like to use the <template> tag since it will not be displayed in the browser and is a good signal when reading the code that this isn’t just an empty div.

This pattern works really well with Turbo Stream responses.

Imagine you have a list of task with an inline form to create a new task. You can submit the form and then send back a <turbo-stream> to append to the list and then scroll the page to the newly created task.

<%= turbo_stream.append :tasks, @task %>

<%= turbo_stream.append :tasks do %>
  <template
    data-controller="scroll-to"
    data-scroll-to-location-value="<% dom_id(@task) %>"></template>
<% end %>

And because we wrap our small bit of JavaScript functionality in a Stimulus controller, all of the lifecycle events are taken care of. No need to listen for turbo:load events, it just works.

What else could you use this for?

Highlighter

We use this highlighter controller to add extra styles when something is “selected”.

<template
  data-controller="highlighter"
  data-highlighter-marker-value="<%= dom_id(task, :list_item) %>"
  data-highlighter-highlight-class="text-blue-600 bg-blue-100"></template>

By using both the Stimulus values and classes APIs, this controller is super reusable: we can specify any DOM element id and whatever classes we want to use to highlight the element.

// app/javascript/controllers/highlighter_controller.js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static values = {
    marker: String
  }
  static classes = ["highlight"]

  connect() {
   this.markedElement.classList.add(...this.highlightClasses)
   this.element.remove()
  }

  get markedElement() {
    return document.getElementById(this.markerValue)
  }
}

Grab focus

We use a grab-focus controller for a form where you can quickly add tasks. Submitting the form creates the task and then dynamically adds a new <form> for the next task. This controller seamlessly moves the browser focus to the new input.

// app/javascript/controllers/grab_focus_controller.js
import { Controller } from '@hotwired/stimulus'

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

  connect() {
    this.grabFocus()
    this.element.remove()
  }

  grabFocus() {
    if (this.hasSelectorValue) {
      document.querySelector(this.selectorValue)?.focus()
    }
  }
}

Analytics “Beacons”

We borrowed this idea from HEY and use it for tracking page analytics. We add a beacon to the page that pings the backend to record a page view and then removes itself.

(If you’re fancy you could even use the Beacon Web API, but we’re justing sending an PATCH request here for simplicity!)

// app/javascript/controllers/beacon_controller.js
import { Controller } from '@hotwired/stimulus'
import { patch } from '@rails/request.js'

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

  connect() {
    patch(this.urlValue)
    this.element.remove()
  }
}

We wrapped this one up in a Rails view helper for a more clean API.

module AnalyticsHelper
  def tracking_beacon(url:)
    tag.template data: { controller: "beacon", beacon_url_value: url }
  end
end

<!-- Inside app/views/layouts/plan.html.erb -->
<%= tracking_beacon(url: plan_viewings_path(@plan)) %>

Wrap it up

Self-destructing Stimulus controllers are a great way to augment Hotwire applications by adding sprinkles of JavaScript behavior without having to completely eject and build the whole feature on the client-side. Keep them small and single-purpose and you’ll be able to reuse them across pages and in different contexts.

Piggybacking on the existing lifecycle of Stimulus controllers ensures that things work as expected when changing content via Turbo Streams and navigating between pages with Turbo Drive.

Tailwind style CSS transitions with StimulusJS

matt swanson — Wed, 01 Jun 2022 13:00:00 +0000

This post is part of Hotwire Summer: a new season of content on Boring Rails!

If you’ve built UI elements with StimulusJS before, you’ve certainly written code to show or hide an element on the page. Whether you are popping up a modal or sliding out a panel, we’ve all written controller code like:

this.modalTarget.classList.remove("hidden")

To take your UI designs to the next level, you can use transitions so elements don’t immediately appear or disappear from the screen. You can transition opacity to gently fade elements in and use translate to slide them into place.

One issue trying to do these kind of animations with CSS transition properties, as Sebastian De Deyne lays out in this excellent primer on enter and leave transitions, is that you can’t change an element’s display property before the transition occurs. We can use basic transition styles for things like subtly changing a button color on hover, but for smooth animations when elements are shown or hidden, we need something more.

One pattern that has emerged from the Vue and Alpine communities is to use a series of data attributes to define your desired CSS classes during the lifecycle of the transition. TailwindUI also follows this pattern when specifying how to animate their components. It has proven to be powerful and easy to understand.

Each project has their own specific naming conventions, but they all define six basic lifecycle “stages”:

Entering: the classes that should be on an element during the whole time it is entering the page (sometimes called “Entering Active”, “Enter Active”, “Enter”, etc)
Enter From: the starting point that you will transition from when entering the page (sometimes called “Enter Start”)
Enter To: the ending point of the transition when entering the page (sometimes called “Enter End”)
Leaving: the classes that should be on an element during the whole time it is leaving the page (sometimes called “Leaving Active”, “Leave Active”, “Leave”, etc)
Leave From: the starting point that you will transition from when leaving the page (sometimes called “Leave Start”)
Leave To: the ending point of the transition when leaving the page (sometimes called “Leave End”)

This picture from the Vue docs really helped me visualize how it all works:

The approach of using data attributes works well with Tailwind’s transition utility classes and feels right at home with the StimulusJS philosophy of augmenting HTML markup.

Vue (Transition) and Alpine (x-transition) provide native, first-party support for these transitions, but for a Rails app using Hotwire, we’ll have to add this functionality ourselves.

Options

I explored a few different options in this space. Here are the most popular approaches I came across:

stimulus-transitions

This library provides a transition controller that you can import and register. You use this controller like a normal Stimulus controller in your application:

<div data-controller="transition"
     data-transition-enter-active="enter-class"
     data-transition-enter-from="enter-from-class"
     data-transition-enter-to="enter-to-class"
     data-transition-leave-active="or-use multiple classes"
     data-transition-leave-from="or-use multiple classes"
     data-transition-leave-to="or-use multiple classes">
  <!-- content -->
</div>

The controller will automatically detect when the element is shown or hidden and run the transitions. There are also options for listening to custom transition:end-enter and transition:end-leave events if you want to run additional code when the transitions have finished.

The transition controller needs something to trigger the display style on the element so you will need an application-level controller to kick off the process.

stimulus-use/useTransition

The stimulus-use project is a collection of reusable behaviors for Stimulus. If you are familiar with React, this project is similar to React’s hooks system, but for Stimulus controllers.

One particular mix-in available in this package is useTransition. You can call this from your own Stimulus controller and it will run the transitions on the element (either reading from data- attributes or you can specify the classes in JavaScript as options).

This particular mix-in was flagged as a “beta” release at the time of this writing.

el-transition

This library is not Stimulus specific, but implements the same Vue/Alpine transition pattern. Since it is vanilla Javascript, there are no built-in hooks for Stimulus lifecycle or controllers to register. You import enter and leave functions directly and then call them while providing the element to transition.

import {enter, leave} from 'el-transition'

// in your stimulus controller somewhere
enter(this.modalTarget)
leave(this.modalTarget)

The whole library is really just one, 60 line file so you can even just drop it into your project directly if you want to vendor it.

My recommendation: el-transition

All three libraries could do what I wanted: apply Vue/Alpine style data- attribute transitions.

I had the most success with el-transition and selected it for my project.

I liked that it was super simple and not tied to the framework. It has a minimal surface-area and I didn’t have to rely on an external library to update for newer Stimulus releases if there are breaking changes.

One extra bonus was that enter and leave functions returned Promise objects, which worked much better for coordinating multiple elements that need to transition (this is pretty common in the TailwindUI components).

Building the Tailwind UI Slide Over Menu

Let’s put this advice into practice by building a slide-over menu from TailwindUI.

Start by grabbing the HTML code template (we’re using one of the free samples for this article).

In this case, we’ll create a slide-over controller, with targets for the three parts in the Tailwind markup (backdrop, panel, and closeButton) and then one more for the whole menu (container).

Notice there are several code comments that highlight various parts of the component and how to transition them.

<!--
  Background backdrop, show/hide based on slide-over state.

  Entering: "ease-in-out duration-500"
    From: "opacity-0"
    To: "opacity-100"
  Leaving: "ease-in-out duration-500"
    From: "opacity-100"
    To: "opacity-0"
-->
<div class="fixed inset-0 transition-opacity bg-gray-500 bg-opacity-75"></div>

For each of these component parts, we’re going to bind them as Stimulus targets and also add in the data attributes to match the specification.

<div data-controller="slide-over">
  ...

  <div data-slide-over-target="backdrop"
      class="fixed inset-0 transition-opacity bg-gray-500 bg-opacity-75"
      data-transition-enter="ease-in-out duration-500"
      data-transition-enter-start="opacity-0"
      data-transition-enter-end="opacity-100"
      data-transition-leave="ease-in-out duration-500"
      data-transition-leave-start="opacity-100"
      data-transition-leave-end="opacity-0"></div>

  ...
</div>

Repeat this for the other elements that we want to animate. We’ll also add a basic <button> to show the panel when clicked.

Here is what the full markup:

<div data-controller="slide-over">
  <button class="form-input" data-action="slide-over#show">Show slideover</button>

  <!-- This example requires Tailwind CSS v2.0+ -->
  <div data-slide-over-target="container" class="relative z-10 hidden" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
    <!--
      Background backdrop, show/hide based on slide-over state.

      Entering: "ease-in-out duration-500"
        From: "opacity-0"
        To: "opacity-100"
      Leaving: "ease-in-out duration-500"
        From: "opacity-100"
        To: "opacity-0"
    -->
    <div data-slide-over-target="backdrop"
      class="fixed inset-0 transition-opacity bg-gray-500 bg-opacity-75"
      data-transition-enter="ease-in-out duration-500"
      data-transition-enter-start="opacity-0"
      data-transition-enter-end="opacity-100"
      data-transition-leave="ease-in-out duration-500"
      data-transition-leave-start="opacity-100"
      data-transition-leave-end="opacity-0"></div>

    <div class="fixed inset-0 overflow-hidden">
      <div class="absolute inset-0 overflow-hidden">
        <div class="fixed inset-y-0 right-0 flex max-w-full pl-10 pointer-events-none">
          <!--
            Slide-over panel, show/hide based on slide-over state.

            Entering: "transform transition ease-in-out duration-500 sm:duration-700"
              From: "translate-x-full"
              To: "translate-x-0"
            Leaving: "transform transition ease-in-out duration-500 sm:duration-700"
              From: "translate-x-0"
              To: "translate-x-full"
          -->
          <div data-slide-over-target="panel"
            class="relative w-screen max-w-md pointer-events-auto"
            data-transition-enter="transform transition ease-in-out duration-500 sm:duration-700"
            data-transition-enter-start="translate-x-full"
            data-transition-enter-end="translate-x-0"
            data-transition-leave="transform transition ease-in-out duration-500 sm:duration-700"
            data-transition-leave-start="translate-x-0"
            data-transition-leave-end="translate-x-full">
            <!--
              Close button, show/hide based on slide-over state.

              Entering: "ease-in-out duration-500"
                From: "opacity-0"
                To: "opacity-100"
              Leaving: "ease-in-out duration-500"
                From: "opacity-100"
                To: "opacity-0"
            -->
            <div data-slide-over-target="closeButton"
              class="sm:-ml-10 sm:pr-4 absolute top-0 left-0 flex pt-4 pr-2 -ml-8"
              data-transition-enter="ease-in-out duration-500"
              data-transition-enter-start="opacity-0"
              data-transition-enter-end="opacity-100"
              data-transition-leave="ease-in-out duration-500"
              data-transition-leave-start="opacity-100"
              data-transition-leave-end="opacity-0">
              <button type="button" data-action="slide-over#hide" class="hover:text-white focus:outline-none focus:ring-2 focus:ring-white text-gray-300 rounded-md">
                <span class="sr-only">Close panel</span>
                <!-- Heroicon name: outline/x -->
                <svg class="w-6 h-6" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true">
                  <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
                </svg>
              </button>
            </div>

            <div class="flex flex-col h-full py-6 overflow-y-auto bg-white shadow-xl">
              <div class="sm:px-6 px-4">
                <h2 class="text-lg font-medium text-gray-900" id="slide-over-title">Panel title</h2>
              </div>
              <div class="sm:px-6 relative flex-1 px-4 mt-6">
                <!-- Replace with your content -->
                <div class="sm:px-6 absolute inset-0 px-4">
                  <div class="h-full border-2 border-gray-200 border-dashed" aria-hidden="true">
                    Your content goes here! How about a lazy-loaded turbo-frame?
                  </div>
                </div>
                <!-- /End replace -->
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

And now we need to actually implement the Stimulus controller to run the transitions.

import { Controller } from "@hotwired/stimulus"
import { enter, leave } from 'el-transition'

export default class extends Controller {
  static targets = ["container", "backdrop", "panel", "closeButton"]

  show() {
    this.containerTarget.classList.remove("hidden")
    enter(this.backdropTarget)
    enter(this.closeButtonTarget)
    enter(this.panelTarget)
  }

  hide() {
    Promise.all([
      leave(this.backdropTarget),
      leave(this.closeButtonTarget),
      leave(this.panelTarget)
    ]).then(() => {
      this.containerTarget.classList.add("hidden")
    })
  }
}

When the show action is called (by clicking the button), we remove the hidden class on the whole container and then run the enter function from el-transition on each of the targets we want to animate. This will fade in the backdrop and close button and slide over the panel using the Tailwind classes we defined in the data attributes.

When we trigger the hide action (by clicking the close button), we do everything in reverse. We run the leave function and the panel slides back over and the backdrop and close button fade away. Once all the transitions are done, we hide the whole container. By using Promise.all we can wait all of the individual transitions to finish (remember they may have different durations!) before hiding the container.

No need for setTimeout or flashing of content when the transition is finished and then removed!

It’s not quite as convenient as dropping in the React or Vue snippets from TailwindUI, but it’s pretty close!

You may want to take this a step further by extracting the markup into a partial or use ViewComponent to clean up the code, but that is left as an exercise for the reader.

Wrap it up

It’s great to follow other front-end communities and bring back ideas into your own ecosystem. Vue and Alpine have established a really clear, understandable pattern for specifying CSS transitions and we can leverage that work in a StimulusJS/Hotwire project with a small library.

These transitions take a bit of time to wrap your head around, but they add a nice level of polish to your UI components with minimal effort: exactly the kind of high leverage techniques we want when building apps in the “boring Rails” style.

Ordinalize: Adding "-st", "-nd", "-rd", "-th" to dates

matt swanson — Wed, 29 Sep 2021 16:44:29 +0000

Ever written a giant case statement to add "-st", "-nd", "-rd", "-th" to display dates like "March 7th" or "September 1st"?

Converting numbers like 1, 2, 7, 19 into "1st", "2nd", "7th", "19th" is called ordinalizing.

ordinalize(number)
Turns a number into an ordinal string used to denote the position in an ordered sequence such as 1st, 2nd, 3rd, 4th.

Instead of manually add special cases, check if your language, library, or framework has a helper built-in.

For example, in Rails, you can call the ordinalize method on a number or use the long_ordinal date format.

> 3.ordinalize
=> "3rd"

> Date.today.to_s(:long_ordinal)
=> "September 29th, 2021"

Happy hacking!

Debugging slow Heroku builds

matt swanson — Mon, 17 May 2021 13:00:00 +0000

It’s always best to follow a systematic approach when trying to speed up slow code.

First, measure the current performance.

Next, make the change that you think will help.

Lastly, measure again to see if the change worked.

It’s no different when it comes to debugging slow test suites or deploys.

I recently noticed that my Heroku deploys were taking nearly 10 minutes to build.

Thanks to a tip from my friend Anthony, I was able to quickly measure, diagnose, and deploy a fix that shaved nearly 4 minutes off every Heroku build. Big win!

Usage

Heroku uses “buildpacks”, which are essentially shell scripts that run to install and configure your server.

You can add multiple buildpacks: it’s common for a Ruby on Rails app to have a Ruby buildpack (for running the Rails app) and a Node buildpack (for building Javascript assets).

But even if you watch the build log as your code changes deploy, there aren’t many affordances for knowing what parts of the process are slow.

Enter the heroku-buildpack-timestamps buildpack!

You can add this buildpack to your Heroku app and it will output timestamps of each step in the process.

2021-05-10 19:30:59
2021-05-10 19:30:59 -----> Creating runtime environment
2021-05-10 19:30:59
2021-05-10 19:30:59 NPM_CONFIG_LOGLEVEL=error
2021-05-10 19:30:59 YARN_PRODUCTION=true
2021-05-10 19:30:59 NODE_ENV=production
2021-05-10 19:30:59 NODE_MODULES_CACHE=true
2021-05-10 19:30:59 NODE_VERBOSE=false
2021-05-10 19:30:59
2021-05-10 19:30:59 -----> Installing binaries
2021-05-10 19:30:59 engines.node (package.json): unspecified (use default)
2021-05-10 19:30:59 engines.npm (package.json): unspecified (use default)
2021-05-10 19:30:59 engines.yarn (package.json): unspecified (use default)
2021-05-10 19:30:59
2021-05-10 19:30:59 Resolving node version 14.x...
2021-05-10 19:31:00 Downloading and installing node 14.17.0...
2021-05-10 19:31:01 Using default npm version: 6.14.13
2021-05-10 19:31:01 Resolving yarn version 1.22.x...
2021-05-10 19:31:01 Downloading and installing yarn (1.22.10)
2021-05-10 19:31:02 Installed yarn 1.22.10
2021-05-10 19:31:03
2021-05-10 19:31:03 -----> Restoring cache
2021-05-10 19:31:03 - node_modules
2021-05-10 19:31:05
2021-05-10 19:31:05 -----> Building dependencies
2021-05-10 19:31:06 Installing node modules (yarn.lock)
2021-05-10 19:31:07 yarn install v1.22.10
2021-05-10 19:34:10 Done in 191.01s.
2021-05-10 19:34:10
2021-05-10 19:34:10 -----> Caching build
2021-05-10 19:34:10 - node_modules
2021-05-10 19:34:17
2021-05-10 19:34:17 -----> Pruning devDependencies
2021-05-10 19:34:17 Skipping because YARN_PRODUCTION is 'true'

I added this buildpack to my staging Heroku app and was able to pinpoint the hot spots in the process. My findings showed that running yarn install was taking 4 minutes, even when there were no Javascript changes between builds.

After identifying the troublesome build step, I decided to turn on the --verbose flag for yarn to see why things were so slow. The official nodejs buildpack is supposed to automatically cache npm packages so it was strange that every build was spending 4 minutes installing.

The --verbose flag generated a huge amount of extra detail to help me find the problem – over 23k lines of logging…

Downloading binary from https://github.com/sass/node-sass/releases/download/v4.13.1/linux-x64-83_binding.node
Cannot download "https://github.com/sass/node-sass/releases/download/v4.13.1/linux-x64-83_binding.node":

HTTP error 404 Not Found

Hint: If github.com is not accessible in your location
      try setting a proxy via HTTP_PROXY, e.g.

      export HTTP_PROXY=http://example.com:1234

or configure npm proxy via

      npm config set proxy http://example.com:8080

Building: /tmp/build_496d129f/.heroku/node/bin/node /tmp/build_496d129f/node_modules/node-gyp/bin/node-gyp.js rebuild --verbose --libsass_ext= --libsass_cflags= --libsass_ldflags= --libsass_library=

Buried deep in the logs was the culprit. We were trying to download a pre-compiled node-sass binary, but it wasn’t found (because Heroku was running Node 14 and the version we asked for was only built for Node 10). After timing out, we then built the native package manually. Aha!

(The fix was to update webpacker).

While this fix was specific to my project, the process is generalizable: measure your Heroku build to find the slow parts, then dig deeper until you can find the underlying problem.

If you find yourself waiting and waiting for your Heroku builds to finish, try adding this buildpack so you can debug why it’s slow.

Quickly explore your data with `uniq` and `tally`

matt swanson — Wed, 05 May 2021 13:00:00 +0000

A common question you may want to answer on user-input data is: what values have been entered and how many times is each one used?

Maybe you have a list of dropdown options and you want to investigate removing a rare-used option.

Ruby has two handy methods that I reach for often: uniq and tally.

Usage

The uniq method operates on an enumerable and compresses your data down to unique values.

Outreach::Task.all.map(&:status).uniq
=> ["Confirmed w/o Outreach",
 "Awaiting Outreach",
 "Responded",
 "No Response Expected",
 "Follow-up",
 "Awaiting Reply"]

While most developers are familiar with uniq, the tally method is one of the best kept secrets in Ruby. The tally method takes an enumerable of values and returns a hash where the keys are unique values and the values are the number of times the value appeared in the list.

Outreach::Task.all.map(&:status).tally
=> {"Confirmed w/o Outreach"=>106,
 "Awaiting Outreach"=>28,
 "Responded"=>48,
 "No Response Expected"=>10,
 "Follow-up"=>4,
 "Awaiting Reply"=>8}

These two methods are great to have in your toolbox to quickly explore your data in a Rails console.

Additional Resources

Ruby API: Enumerable#uniq

Ruby API: Enumerable#tally

Improving your Rails mailers with `email_address_with_name`

matt swanson — Mon, 03 May 2021 13:00:00 +0000

In almost all email programs, you can add a display name before your email address like so:

To: Matt Swanson <matt@example.com>

It’s a small touch, but it is a more human-readable way of addressing an email. Rails provides a helper utility to format email addresses in this style without resorting to manual string manipulation.

Usage

Use email_address_with_name to add a name in-front on an email address in a standard way

ActionMailer::Base.email_address_with_name("swan3788@gmail.com", "Matt Swanson")
=> "Matt Swanson <swan3788@gmail.com>"

This helper is available in all Rails mailers.

class UserMailer < ApplicationMailer
  default from: 'notifications@example.com'

  def welcome_email
    @user = params[:user]

    mail(
      to: email_address_with_name(@user.email, @user.display_name),
      subject: 'You have a new message'
    )
  end
end

Options

This helper handles nil gracefully as well.

ActionMailer::Base.email_address_with_name("swan3788@gmail.com", nil)
=> "swan3788@gmail.com"

And it handles escaping characters automatically:

ActionMailer::Base.email_address_with_name("mike@example.com", "Michael J. Scott")
=> "\"Michael J. Scott\" <mike@example.com>"

ActionMailer::Base.email_address_with_name("chip@example.com", 'John "Chip" Smith')
=> "\"John \\\"Chip\\\" Smith\" <chip@example.com>"

Additional Resources

Rails API: ActionMailer::Base#email_address_with_name