Thomas Cannon's Blog

Flip on the Awesome

2025-04-06T00:00:00Z

Flip on the Awesome

Overhauling an app’s view layer without halting development

I’ve been facing a gnarly problem for the past year: what does a maintainable view layer look like in Rails? I’ve seen a different approach for every app I’ve worked on, and none of them have particularly fit the bill.

For the 1^st version of the Practical Framework, I opted to dip my toes into Phlex 1. That approach served me well, allowing me to ship 2 apps in about a year. But then the tech debt bill came due from multiple angles.

First: Web Awesome is nearing release. I’d hand-spun a frontend framework as an exercise in how to do so, and as a stopgap, but it frankly didn’t meet my quality standards long-term. So I knew I needed to replace it with Web Awesome when the time came.

Second: Phlex 2.0 hit; which is a radical shift. I tried to upgrade what I had, realized it’s now much more opinionated and wants to handle the entire rendering stack. So I stepped back to square 1 to reevaluate the landscape.

Third: practice reared its ugly head. Having built out a design system and frontend framework, gotten experience with multiple perspectives and approaches to the frontend, and shipped multiple products; I knew a lot more than I did in 2023. Plus, what’s widely available in browsers set the stage for some truly maintainable codebases.

So, I spent months agonizing over different libraries, debated with folks about how to structure view code, and (most importantly) ported over an entire app to figure out the best way to actually ship a view layer overhaul so that it doesn’t freeze an entire development team in its tracks.

This guide tries to walk you through the things I learned, the approach I took, and why I’ve found a component-first, intentionally structured view layer backed by ViewComponent is the best way forward for Rails apps. And how to use feature flags and view variants to chip away at the project.

How to read this guide

This guide is long, and covers a lot of ground. The structure is:

Discuss the big-picture plan and tools used, in general terms
Dig into some problem areas, principles, and tactics I applied
Some miscellaneous tips and bits of advice

I recommend opening up the repo to look at the code while reading through this guide. I’ll also include links to specific files when discussing particular topics. There is also this list of focus areas in the README.

After reading, I highly recommend forking the repo and playing around. You might not like how I built parts of it, you might want to refactor—this is a playground for you to test ideas and see how it works in a production app that’s just complex enough to really stretch your legs.

What is Dispatcher?

It is an app I was commissioned to write, which I use as testbed. I’ve opened sourced a snapshot of the app right when I turned on the alpha for the Web Awesome UI, to act as a public resource for folks to study.

It’s a simple job and onsite management tool for service companies. The office specifies a job, the tasks it requires, sets up onsites, and assigns tasks to those onsites. Onsites can have notes attached to them. Your standard states & priority flags apply as well.

What is `PracticalFramework`? What is `PracticalViews`?

PracticalFramework is the layer I’m building on top of Rails to be used across a suite of apps. It’s meant to distill and standardize solutions to common problems across many apps, and will eventually be open-sourced. The versions in these snapshots are pre-releases, not documented and or refined for public use.

PracticalViews is the namespace I’m using for this 2^nd iteration of the framework’s view layer. I needed a wholly separate namespace to avoid collisions, and I was frankly tired of having to write PracticalFramework::Components:: before everything.

The Big Picture

Tools used

Flipper

Flipper is the feature flag library I use. This gives you the distinct advantage of not having a long-running branch for the overhaul, with all the nightmare merge commits and rebasing. You tackle it piecemeal, just like you would a Rails upgrade with the dual-boot method.

You can use whatever feature flag approach that you want; it doesn’t matter. I use Flipper because it’s simple, straightforward, and Just Works™.

ViewComponent

ViewComponent is a library for building components in Ruby on Rails. Initially developed at GitHub; it is mature, fairly flexible, and supports a wide variety of beliefs around componentization—from everything being a component, to lightweight wrappers around handcrafted markup.

Web Awesome

Web Awesome is the frontend component library Practical Computer will be using going forward.

Lookbook

Lookbook is A UI preview tool for components in Rails apps, akin to Storybook. It supports ViewComponent out of the box, and allows you to quickly iterate & review your component library.

Oaken

Although I didn’t get around to using Oaken to build the seeds for my Lookbook previews, it’s an invaluable tool I install on every project I can.

The phases of a View Layer overhaul

With incremental PRs and feature flags, the daunting task of a UI overhaul becomes manageable

Prepare:
- Decide on big-picture conventions, front-end frameworks, etc.
- Identify pain points in your existing view layer that you want to eliminate (eventually!)
- Ensure your controller layer is at the quality level you can live with for both UIs. Technically, you can defer this for problem areas until you port that area over, or kick the can to post-overhaul, but generally speaking, you’re going to be living with your existing controller layer for a while.
Sketch new view layer foundation
- Build the “kernel” of the new view layer, using View Variants & separated asset builds.
- Create a few of your foundational ViewComponents.
Port existing UI to components.
- A slog, broken up into smaller PRs to keep the project manageable.
- Focus solely on porting the existing behavior; do not get sidetracked into improving existing behavior (aside from 5 minute treats).
- Only tackle the view layer, your requests should remain the same between both versions of the UI. Put another way: everything from the controller layer up should not change.
- Work at a steady pace, with intention, to keep momentum and refine lessons as the problem space is fresh.
- Don’t worry about tests or previews at this stage, you have bigger problems to tackle (like the scale of porting).
Once everything is ported, then get the test suite green against the new UI.
- Patch tests based on which version of the UI is running.
- Keep patches focused on minimal changes, gated behind feature flags.
Now that everything is ported over to components, do an internal polishing pass.
- This is when tests and previews get setup.
Gradual rollout to customers
- Initial alpha release, then percentage-based gradual releases.
- Fix bugs as they crop up, you get to choose the impact of bugs by the sample size of customers using the new UI.
Once the rollout is complete, cleanup and remove the old UI.

How to overhaul your view layer while continuing to ship features

In short: Feature Flags! You’re going to be building a whole new version of the UI, gated behind a feature flag. This will let you keep merging code back into main, tackle other important projects, and chip away at the UI with minimal overhead.

Keep the old & new view code totally separate with view variants and different asset builds

To reduce bugs and avoid carrying over unused code to the new pastures; you should use Rails’ request variants to build your new views. This allows you to build an entirely new view stack in parallel to your existing one, keeping your existing view code untouched. You can experiment away, take radical swings, find the best path forward without breaking the code that keeps your business running.

In ApplicationController, I added a before_action to switch the variant based on whether we were rendering the Web Awesome UI:

def using_web_awesome?
  if has_current_organization?
    Flipper.enabled?(:web_awesome, current_organization)
  else
    Flipper.enabled?(:web_awesome, FlipperNoOrganizationActor.instance)
  end
end

def set_webawesome_variant
  return unless using_web_awesome?
  request.variant = :webawesome
end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/controllers/application_controller.rb#L70-L82

With that, I could tackle each controller view one at a time; and ended up with directories that looked like this:

app/views/organizations/jobs/_datatable_form.html.erb
app/views/organizations/jobs/_form.html.erb
app/views/organizations/jobs/_job_table.html.erb
app/views/organizations/jobs/_job_table_row.html.erb
app/views/organizations/jobs/edit.html+webawesome.erb # New Web Awesome Version
app/views/organizations/jobs/edit.html.erb
app/views/organizations/jobs/index.html+webawesome.erb # New Web Awesome Version
app/views/organizations/jobs/index.html.erb
app/views/organizations/jobs/new.html+webawesome.erb # New Web Awesome Version
app/views/organizations/jobs/new.html.erb
app/views/organizations/jobs/show.html+webawesome.erb # New Web Awesome Version
app/views/organizations/jobs/show.html.erb

It’s a little messy, but it’s baked into the framework and widely supported.

Make sure to also check out app/layouts, to see how the entire view stack is fresh ground because of view variants.

For the Javascript & CSS, I created entirely new entrypoints, prefixed with v2-* to help keep things separated.

app/javascript/application.js
app/javascript/boot.js
...
app/javascript/chunks/kernel.js
app/javascript/chunks/v2-kernel.js
app/javascript/elements/index.js
app/javascript/elements/google-place-autocomplete.js
app/javascript/elements/v2-index.js
app/javascript/elements/v2-google-place-autocomplete.js
...
app/javascript/theme-toggle.js
app/javascript/v2-application.js
app/javascript/v2-boot.js
## ...

There is technically duplicated code in this structure, but it’s a tradeoff for keeping things siloed to avoid bugs and make cleanup post-migration easier. Depending on your needs & codebase, it is possible to refactor shared code into utility files to reduce duplication.

Why ViewComponent?

A lot of time was spent debating between Phlex or ViewComponent. Especially because Dispatcher was built with a lot of Phlex 1 components, and I like Phlex’s ergonomics!

There are a few factors that led to ViewComponent winning out over Phlex 2+:

Phlex 2+’s strongly encouraged design ethos that the entire view stack to be Phlex-based
The knock-on effects of Phlex 2+’s push for structured document rendering, versus Rails’ buffer-based rendering (which ViewComponent extends)
ViewComponent accomplishing almost everything that I needed for my view layer; once I enabled the experimental capture patch

I actually did try migrating to Phlex 2; which was a massive undertaking. But right at the end of migrating Dispatcher, I ran into some breaking issues with form builders, which I use extensively.

The “Experimental” capture patch

I’d initially written off ViewComponent due to this section of the Known Issues

ViewComponent isn’t compatible with form_for helpers by default.

Passing a form object (often f) to a ViewComponent works for simple cases like f.text_field :name. Content may be ill-ordered or duplicated in complex cases, such as passing blocks to form helpers or when nesting components.

Some workarounds include:

Experimental: Enable the capture compatibility patch with config.view_component.capture_compatibility_patch_enabled = true.

At first glance, a non-starter. But, after taking Kasper Timm Hansen’s Deep Dive into ActionView, I finally understood how it composes buffers and the way ViewComponent hooks into ActionView. That, plus some more detective work, led me to find out that the capture patch was merged on February 2023. So it’s had 2+ years of incubation; worth experimenting! And it turned out to work just as expected!

I did have to patch the patch, but that seems to only be due to having existing Phlex 1 components. The patch itself is tiny: just check that the block_context has a class before trying to check if it’s a subclass.

Why Web Awesome?

Having researched, debated, and chewed on the problem of component libraries, their dependence on Javascript, and the people behind them; Web Awesome has come out as the winner. The team behind it believes in the foundations of the web, they’ve shipped native styles that mirror their components so you don’t need to rely on Javascript for your app to be functional, and have thought through the problems of maintenance and customizability.

Even in its alpha state, it’s been a joy to work in and has generally worked with only minor issues.

I’m not particularly worried about having to redo all of my work once the full version is released. Because the new view layer is component-based, applying fixes is a matter of changing the components and they will propagate across the entire app. That, and the time investment that comes with porting, it was better to get started on the migration now rather than wait for 1.0.

Problem Areas, Principles, and Tactics

Avoiding the pitfalls of a UI overhaul

UI overhauls are dangerous, daunting tasks. They shouldn’t be taken lightly, and they’re a long-term investment. Unfortunately, they’re also necessary!

To keep the project on track, you need to keep the following in mind:

The scope needs to be kept strictly in check

For the migration, only focus on the view layer. As much as possible, do not touch from the controller layer upwards. Otherwise, the scope of the project will spiral out of control. It’ll also become a maintenance nightmare, as you juggle the behavior of 2 different UI implementations. It’s much better to accept the current state of your backend while you overhaul your view layer.

If you do need to tackle stuff in the controller layer, that should be done with feature flags An example of this is rendering flash messages. In Dispatcher, I’ve taken the approach of having rich payloads for my flash messages, which are then serialized at render-time. Since there is an entirely new view layer, I needed to patch the original flash helpers from PracticalFramework to return icons from the IconSet if using_web_awesome?

## app/controllers/concerns/patched_flash_helpers.rb

module PatchedFlashHelpers
  extend ActiveSupport::Concern

  def default_notice_icon
    if using_web_awesome?
      return helpers.icon_set.info_icon
    else
      return helpers.icon(style: 'fa-duotone', name: 'circle-info')
    end
  end

  def default_alert_icon
    if using_web_awesome?
      return helpers.icon_set.alert_icon
    else
      return helpers.icon(style: 'fa-duotone', name: 'triangle-exclamation')
    end
  end

  def default_success_icon
    if using_web_awesome?
      return helpers.icon_set.success_icon
    else
      return helpers.icon(style: 'fa-duotone', name: 'circle-check')
    end
  end
end

Relevant files:

This is why it’s important to use feature flags and small PRs, because as you build out the new UI using components, you’ll change your approach. Something that seemed good in isolation might need reworked. A component’s shape will change. Something that was a component will end up as a helper method.

I think view componentizing your UI for the first time is akin to your first moves from spaghetti code to OOP. You stare into the void, and it’s staring back into you. You’re going to get things wrong and the process is going to change you a little bit. That’s scary, but good things can come from it.

You’re also not going to be as productive as you think you’ll be, because you’re actively growing and changing your approaches. So while you think you might be going from A to B while migrating, you’re actually going from 1 to 5. And you need to through 2, 3, and 4 to get there properly.

Why do seasoned developers balk at componentization?

A quirk I’ve consistently run into with Rails developers (even highly experienced ones!) is resistance towards a component structure for view code.

My theory is that it’s a combination of:

Lack of good examples of non-trivial, non-painfully generic components that are difficult to maintain.
Lack of techniques on how to approach the problem at scale with existing codebases.
Visceral pushback against reactive frameworks and the complexities they introduce.
An outdated understanding of what the browser brings to the table.
Pushing back on the overcorrection of “components all the way!”

Lack of examples & techniques

I’m trying to address the lack of examples and techniques with this guide, and by publishing that snapshot of a production repo. It is deliberately not meant to be the ideal end-state. It’s a snapshot of Dispatcher when I finished the most arduous task of the migrating: porting the view layer so that there is a component-first version.

There are bits of the code I’m unhappy with, improvements to clean up early prototypes, the new design’s markup is definitely WIP. But all of those are known, solvable problems you either have experience with, or can find other resources for. As far as I know, there aren’t many examples of this kind of production-grade snapshot freely available to tinker with and analyze.

Reactive frameworks poisoned the well on great ergonomics

Let me show a quick Swift UI example (pulled from Hacking With Swift):

struct let ContentView: View {
  menu = Bundle main.decode([MenuSection].self, from: "menu.json" )

  var body: some View {
    NavigationView {
      List {
        ForEach(menu) { section in
          Section (header: Text (section.name)) {
            ForEach (section.items) { item in
              Text (item. name)
            }
          }
        }
      }
      .navigationTitle ("Menu")
      .listStyle(GroupedListStyle())
    }
  }
}

From Hacking with Swift

Don’t worry about the specifics too much, but keep the general feeling in mind. The reason I mention Swift UI specifically is that the promise behind its intention is:

You write what is essentially markup, and let the platform determine the implementation details.

I think the React/Reactive UI paradigm has poisoned the well in people’s mind on these ergonomics. The problem is that this approach is commonly associated with reactive UIs, which are just too gnarly for most apps.

But remove the reactive UI aspect from your mind, and focus on this example just as a way to render a view that has a traditional lifecycle. This approach to view rendering can act as a force-multiplier for building and maintaining complex apps. It allows you to set up your intentions for how an app behaves, then apply those intentions in various contexts. Implementation details are propagated throughout the app with small PRs, and the behavior is consistent because the code you wrote is based on the intention, not the presentation. Especially if you take care when building out your components at the atomic level, then provide good intentional abstractions. A good modal dialog component will ensure that every modal dialog in your app behaves the same way, but doesn’t get in the way of a specific part of the application.

So, the gap here is providing an abstraction for the view rendering. At the application level, if I’m running a suite of apps (or a single complex app), I (ideally) don’t want to care about the specific markup for a dropdown menu in 90% of cases. I’ve already made all those choices beforehand. And when I fix bugs, I want to be able to apply those fixes across the board. It’s a foundational principle of OOP.

Critics argue this is overkill for most applications; I argue it’s simply a different set of skills that have been historically downplayed (like the skill set required to write good HTML & CSS). You need to understand cascading, composition, the balance of flexibility & intention.

The browser is bringing a lot more to the table

Before the prevalence of componentized HTML frontends, the view layer for Rails apps could best be described as “spaghetti, refined.” Every view is (by and large) bespoke, with some logic shared between them.

Part of this is a framework problem, Rails has always punted on maintainable view code and scoffed at the criticisms that what it ships is not maintainable. I’ve already written 3,000+ words about Rails’ networking stack, so moving on.

Another part is that the landscape & tooling in browsers was very fresh and in flux until the 2020s.

But browsers have made significant advancements in enabling componentized frontend code. To name a few:

CSS Layers
Custom elements
ESM support
The move away from callbacks to async code.

All of these features allow you to break up your code into layers that compose on top of each other, instead of being tightly coupled.

Components aren’t a panacea

There’s justifiable fear and uncertainty about adopting components and whether it’s a good idea for your app. It’s a daunting paradigm shift that seasoned developers don’t usually face. And if they have faced it, it’s generally been intrinsically tied with reactive UIs, Hail Mary product rescues (that often fail), or dysfunctional product management.

People only look at the view layer once it’s too late; so they overcorrect and try to go completely rigid with full-on componentization. It’s one of the clearest places where the growing pains of an application over time become apparent. Models, controllers, services, etc. get refactored and cleaned up constantly because they’re high-traction. It’s rare that a part of the view layer gets revisited unless new features are added or a major performance issue stems from the view layer.

You can’t simply go all-in on components and expect everything to be hunk-dory and perfect. Poorly applied, it leads to a ton of indirection and rigidity. You lose the fun of prototyping. A bad framework can cripple your app. This is a deliberate decision you have to make, knowing the tradeoffs that are going to come from it in terms of the risk of overhead/indirection. But, like all good frameworks; there is the possibility of it significantly improving maintainability. It requires good stewardship, and respect for the craft.

When you get to the point where you’re overhauling your UI, you get the chance to adopt this new landscape, change your approach, and learn from your mistakes. Adopting ViewComponents is not about making everything rigid beyond flexibility. What are the patterns, details, and rules you want to lock-in to components so that you are free to tackle other problems? When do you let something live freeform, and when do you realize it needs to be encapsulated in a component?

Good view code is intentionally revealing, and components are a tool to help structure your intentions. A good view layer allows for fluidity, experimentation, and (some) messiness. There’s a reason why sheet music is not strictly followed. Part of a song’s performance is up to the interpretation of the players. Carefully adopting ViewComponents involves choosing where to be rigid.

Componentization beyond toy examples and tutorial blogs

Another problem that proponents of componentization run into is the lack of good, real-world examples to point to. Articles & tutorials about component libraries and using ViewComponents have examples that are far too rudimentary to convince a seasoned developer. They’re right to be skeptical! Show them the evidence!

Again, why I published that snapshot of Dispatcher! It’s not perfect, but I’d argue it’s pretty good. And it’s actual production code of an alpha state.

I want to dig into two specific examples from Dispatcher, to highlight the benefits of components to solve two specific problems that would be a nightmare to tackle in spaghetti views:

Polishing an app-wide UI component
Replacing old code with native browser features

Polishing an app-wide UI component

Improving the markup around inputs and field titles

Generally, form inputs have a similar structure:

The label for the field
The input itself
The error messages for this field

In Dispatcher, this is broken up into 2 components:

PracticalViews::Form::FieldTitleComponent
PracticalViews::Form::InputComponent

In the actual form code, these are extracted into helper methods (we’ll go over this later in the guide):

## app/views/components/forms/job_form_component.html.erb
<%= f.input_component(:name) do |component| %>
  <% component.with_label do %>
    <%= f.field_title(icon: helpers.icon_set.job_name_icon, title: "Name") %>
  <% end %>

  <% component.with_field do %>
    <%= f.text_field(:name,
      placeholder: t("dispatcher.placeholders.job_name"),
      autofocus: true,
      autocomplete: "none",
      required: true,
      data: {"focusout-validation": true}
    ) %>
  <% end %>
<% end %>

When I was porting over everything to Web Awesome, using these components, I did not have to care about polishing. I could focus on keeping the momentum for porting, because maintainable polishing is baked into the nature of components. At any point in the future, I can clean up how either of these components render, agonizing over the spacing, typography, structure, accessibility; and the changes will be propagated app-wide.What would be a 3,000 line copy/paste PR is reduced to a 30-line, 10 minute code review.

Replacing old code with native browser features

Changing “open dialog” buttons to use the Invoker Commands API if it becomes Baseline

For those who haven’t checked out the Invoker Commands API:

The Invoker Commands API provides a way to declaratively assign behaviors to buttons, allowing control of interactive elements when the button is enacted (clicked or invoked via a keypress, such as the spacebar or return key).

[…]

Historically creating these kinds of controls has required JavaScript event listeners added to the button which can then call the APIs on the element they control. The commandForElement and command properties provide a way to do this declaratively for a limited set of actions. This can be advantageous for built-in commands as the user does not have to wait for JavaScript to download and execute to make these buttons interactive. [MDN]

This is great; I hope it ships and becomes a Baseline feature! And when it does, I can easily upgrade my entire app to use the API with a tiny PR.

All modal dialogs in Dispatcher use the PracticalViews::OpenDialogButtonComponent. This component currently writes inline Javascript on the onclick handler to open a dialog based on its ID:

## app/views/components/practical_views/open_dialog_button_component.rb
class PracticalViews::OpenDialogButtonComponent < PracticalViews::ButtonComponent
  attr_accessor :dialog_id

  def initialize(dialog_id:, appearance: nil, color_variant: nil, size: nil, options: {})
    options = options.with_defaults(
      onclick: self.class.inline_js_to_open_dialog(dialog_id: dialog_id)
    )
    super(type: :button, appearance: appearance, color_variant: color_variant, size: size, options: options)
  end

  def self.inline_js_to_open_dialog(dialog_id:)
    return "document.getElementById(`#{dialog_id}`).showModal()"
  end
end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/views/components/practical_views/open_dialog_button_component.rb

It’s not perfect, but it’s the most error-resistant way to ensure dialog buttons always work, regardless of the state of the rest of the application’s JS.

When the Invoker Commands API becomes Widely available, I can change this component (and the PracticalViews::ModalDialogComponent), and again, the changes will be propagated app-wide.

These are not toy examples, they are foundational UI components that every app needs. These two components are basically in every single view for the app, in one way or another. They dictate foundational experiences people have using your software. Taking a component-first approach changes maintenance tasks that would constantly be pushed back because the benefits outweigh the effort required into lazy Friday PRs.

Learning more about componentization

Even though I strongly disagree with the use of Tailwind, Jeremy Smith’s talk “Refactoring Volatile Views into Cohesive Components” has some great breakdowns in how views get complex, and ways that components can help mitigate that complexity.

Decouple `FormBuilders` with sidechained components

I know FormBuilders have a bad reputation and are discouraged by some because they’re too tightly coupled with the ActiveModel layer.

From my experience, FormBuilder encapsulates two different features:

Mapping a model (virtual or otherwise) to properties that are needed for HTML forms
Rendering the markup necessary for HTML forms

FormBuilders markup rendering is too annyoing to extend out of the box.

The first feature is an extreme time saver, and shouldn’t be discarded. Not having to think about parameter name/value serialization for forms, accessing errors for particular fields, and having a generalized interface for accessing the underlying model are all invaluable time savers.

The second feature is…lacking for any complex application. Mucking around with tag concatenation & generating markup from within a general-purpose class that also intermingles methods for those time saver features above is a recipe for brittle code that only a few people can maintain.

It also doesn’t help that FormBuilders are extremely undocumented, I’d never fully realized their utility & purpose until 2023. And that one of the largest extensions of FormBuilders is Simple Form, the bane of my existence.

Let’s take a detour to talk about why Simple Form is bad because it highlights the problems of:

Overgeneralization
Bad API design
Inflexibility

Overgeneralization & Inflexibility

Simple Form shoves everything into an input method, which doesn’t account for the fact that UIs cannot be fully standardized. Not every field should be rendered the same way; heck, not every text field is rendered the same way. That means that your forms are all funneled into the same markup flow, regardless of whether it actually makes anything sense for that particular UI element.

And because Simple Form is designed to overtake your entire form rendering pipeline, it’s not easy to make modifications. You can’t sidestep Simple Form to say

Listen, I know this form is going to be different than the others you’ve seen before. That’s okay. Don’t panic. I’m a professional, I’ve got this.

Bad API Design

Simple Form does have a way to extend or customize inputs. The problem is that it’s one of the single worst developer experiences I’ve ever had to deal with. Everything is handled through a configuration block, requiring restarts to see any changes. There isn’t a way to just…specify the markup for a particular component, you have to wrap everything in tags. If you want to do stuff like add a wrapper element, that’s all handled with nested options: hashes that are a roll of the dice.

By the time you’d figure out how to make Simple Form work, you’re too exhausted and frustrated to actually care about the user experience. So you slap together something and let the customer deal with the remaining pain.

Sidechained `ViewComponents`

However, a clever application of ViewComponents sidesteps this problem. By creating a series of components that take in a FormBuilder instance, you can sidechain the rendering back to the View Layer. This keeps as much of the complexity of rendering markup in the View Layer (where it belongs) and out of the FormBuilder. And with good API design, you can keep your underlying FormBuilder close to its vanilla state to handle the edge cases & wholly bespoke UI.

By sidechaining the rendering of markup into optional ViewComponents, FormBuilders are significantly more maintainable and useful.

Example: `Form::InputComponent`

Let’s look at a common UI component that Simple Form purports to solve: Wrapping a field with a label, and the errors for that specific field.

This is how the component is used in the actual form:

# app/views/components/forms/job_form_component.html.erb
<%= f.input_component(:name) do |component| %>
  <% component.with_label do %>
    <%= f.field_title(icon: helpers.icon_set.job_name_icon, title: "Name") %>
  <% end %>

  <% component.with_field do %>
    <%= f.text_field(:name,
      placeholder: t("dispatcher.placeholders.job_name"),
      autofocus: true,
      autocomplete: "none",
      required: true,
      data: {"focusout-validation": true}
    ) %>
  <% end %>
<% end %>

All the forms in the new View Layer use a lightweight subclass of ActionView::Helpers::FormBuilder. This is where the input_component helper method is defined:

## app/lib/practical_views/form_builders/web_awesome.rb
class PracticalViews::FormBuilders::WebAwesome < ActionView::Helpers::FormBuilder
  # …

  # also shown because it is used by the example above
  def field_title(icon:, title:)
    template.render(PracticalViews::Form::FieldTitleComponent.new) do |component|
      component.with_icon {
        template.render icon
      }

      title
    end
  end

  def input_component(object_method, label_options: {}, &block)
    template.render(PracticalViews::Form::InputComponent.new(
      f: self,
      object_method: object_method,
      label_options: label_options
    ), &block)
  end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/lib/practical_views/form_builders/web_awesome.rb

This helper method is deliberately lightweight: it’s meant to DRY up using this ViewComponent, keeping the end-result forms less boilerplate, while not caring at all about the end-result markup.

This is what the Form::InputComponent looks like:

## app/views/components/practical_views/form/input_component.rb
class PracticalViews::Form::InputComponent < ViewComponent::Base
  attr_accessor :f, :object_method, :label_options

  renders_one :label
  renders_one :field

  def initialize(f:, object_method:, label_options: {})
    self.f = f
    self.object_method = object_method
    self.label_options = label_options
  end
end

## app/views/components/practical_views/form/input_component.html.erb
<section class='wa-stack wa-gap-3xs'>
  <%= tag.label(**label_options) do %>
    <%= label %>
    <%= field %>
  <% end %>
  <%= f.field_errors(object_method) %>
</section>

This component might look trivial, but its power comes from a combination of:

Restraint in its design.
Effective use of ViewComponent slots
The ability to propagate changes app-wide

The restraint is what I want to focus on most here. Where Simple Form tries to gobble up the rendering of the label and field, this component provides a slot. It does not care how you render the field or label, it simply puts them in the right place. This means that you have flexibility for the edge cases, but a common structure.

One edge-case example in Dispatcher is the “Estimated Duration” field in the Job Task form. This field has the label, but there is also a tooltip in the label that shows different examples of how the field is parsed:

app/views/components/forms/job_task_form_component.html.erb
<%= f.input_component(:estimated_duration) do |component| %>
  <% component.with_label do %>
    <% tooltip_id = helpers.dom_id(form, :estimated_duration_help) %>
    <span class="wa-cluster">
      <%= f.field_title(icon: icon_set.estimated_duration_icon, title: "Estimated Duration") %>

      <%= render icon_set.help_icon_with_tooltip(id: tooltip_id) %>
      <%= tag.wa_tooltip(for: tooltip_id) do %>
        <table>
          <caption>
            <aside class="wa-center"><%= t("dispatcher.job_tasks.form.estimated_duration_popover.title") %></aside>
          </caption>
          <tr>
            <th><code>1:20</code></th>
            <td>1 hour, 20 minutes</td>
          </tr>
          <tr>
            <th><code>90</code></th>
            <td>90 minutes</td>
          </tr>
          <tr>
            <th><code>1:</code></th>
            <td>1 hour</td>
          </tr>
        </table>
      <% end %>
    </span>

  <% end %>

  <% component.with_field do %>
    <%= f.text_field(:estimated_duration,
      placeholder: t("dispatcher.placeholders.estimated_duration"),
      autocomplete: "none",
      required: true,
      data: {"focusout-validation": true}
    ) %>
  <% end %>
<% end %>

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/views/components/forms/job_task_form_component.html.erb

Because input_component is unopinionated in what the label or field look like, we have complete freedom to customize this field in particular. It’ll be structured just like the other input components, even using the field_title to maintain consistency with the label titles. The tooltip can live directly in the form because making it its own component (or subclassing the field title component) would be a waste of time and too much indirection. It’s a one-off UI element.

Also note that the none of the customer form helpers override the critical methods from ActionView::Helpers::FormBuilder. The goal here is not to replace the vanilla form builder, but provide our own set of helpers that extend the good parts of a form builder. This means that any Rails developer can hop in to contribute because they are still using the fundamentals; there are just some helper methods to streamline the code. And because the original form builder is untouched, we can go directly “to the metal” for truly custom cases.

Example: `Forms::LocationFieldComponent` (Application-specific input component)

In Dispatcher, onsites & jobs both have locations. This is because a job could be pointed to one place (like a corporate HQ), while an onsite would be for a specific branch. Both use a GooglePlace model, and need the same UI element for setting the location. Time for ViewComponent to shine!

# app/views/components/forms/location_field_component.rb
class Forms::LocationFieldComponent < ApplicationComponent
  attr_accessor :f, :object_method, :location_field_name

  def initialize(f:, object_method:, location_field_name:)
    @f = f
    @object_method = object_method
    @location_field_name = location_field_name
  end

  def field_name
    f.field_name(object_method)
  end

  def field_value
    return nil if google_place.blank?
    JSON.generate({formatted_address: google_place.human_address, place_id: google_place.google_place_api_id })
  end

  def google_place
    return nil unless f.object.respond_to?(object_method)
    return f.object.public_send(object_method)
  end

  def location_field_value
    google_place&.human_address
  end
end

## app/views/components/forms/location_field_component.html.erb
<%= tag.google_place_autocomplete(name: field_name, value: field_value) do %>
  <%= f.text_field(
    location_field_name,
    data: {"autocomplete-element": true},
    autocomplete: "none",
    value: location_field_value
  ) %>

  <small data-formatted-address-hint class="wa-flank wa-gap-xs wa-quiet">
    <%= render helpers.icon_set.formatted_address_icon %>
    <span><slot name="formatted_address"><%= location_field_value %></slot></span>
  </small>
<% end %>

This component is flexible: it takes any FormBuilder, accepts any name the GooglePlace instance uses in the model, and can use any field name you want it to. The google-place-autocomplete is a Custom Element that wraps the Google Places API on the JS side.

Following the Rails convention of having an Application* Base class, it’s easy for Dispatcher to extend the PracticalViews framework with its own custom inputs:

## app/form_builders/new_application_form_builder.rb
class NewApplicationFormBuilder < PracticalViews::FormBuilders::WebAwesome
  def location_field(object_method:, location_field_name:)
    template.render(Forms::LocationFieldComponent.new(
      f: self,
      object_method: object_method,
      location_field_name: location_field_name
    ))
  end
end

Bringing it all together, the flexibility of our InputComponent means that this custom component fits perfectly into our forms as if it was there all along:

app/views/components/forms/job_form_component.html.erb
<%= f.input_component(:location, label_options: {for: f.field_id(:location)}) do |component| %>
  <% component.with_label do %>
    <%= f.field_title(icon: helpers.icon_set.location_icon, title: "Address") %>
  <% end %>

  <% component.with_field do %>
    <%= f.location_field(object_method: :google_place, location_field_name: :location) %>
  <% end %>
<% end %>

Using these approaches; you can build forms that behave consistently, are maintainable by everyone on the team, and don’t get in your way.

Sane icon management with an `IconSet` PORO

Maintaining & applying icons across a complex project can be a maintenance nightmare. A delightful app has numerous icons, with good variety, and keeps the icon set refreshed & looking sharp.

Some strategies used for getting icons into the view are:

Shared partials, which are a pain to call and hard to maintain
Putting all the icons in a single, IconHelper helper; but that pollutes the view namespace and is a flat hierarchy that is hard to extend or adjust.

An icon makes a great component, especially Font Awesome icons given the number of families, variants, and customization options:

# app/views/components/practical_views/icon_component.rb
class PracticalViews::IconComponent < PracticalViews::BaseComponent
  include ActiveModel::Serializers::JSON

  attr_accessor :name, :family, :variant, :fixed_width, :label, :options

  def attributes=(hash)
    hash.each do |key, value|
      public_send("#{key}=", value)
    end
  end

  def attributes
    { "name" => nil, "family" => nil, "variant" => nil, "fixed_width" => nil, "label" => nil, "options" => nil }
  end

  def initialize(name:, family:, variant: nil, fixed_width: true, label: nil, options: {})
    self.name = name
    self.family = family
    self.variant = variant
    self.fixed_width = fixed_width
    self.label = label
    self.options = options
  end

  def call
    tag.wa_icon(**mix({
      "name": name,
      "family": family,
      "variant": variant,
      "fixed-width": fixed_width,
      "label": label
    }, options))
  end
end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/views/components/practical_views/icon_component.rb

The problems with an IconComponent on its own are:

Applying the same icon across an app, while keeping it maintainable to adjust said icon
The verbosity of calling render IconComponent.new(name: ...) any time you want to put an icon on a page
Setting up presets
Aliasing the same icon for multiple contexts so you have to think less

You could create a series of helper methods that return these icons in an IconHelper helper. But, a better approach is to borrow a page from the Apple Ecosystem, with the idea of “Asset Bundles.”

In iOS/Mac/etc. apps, Asset Bundles are a collection of images/files/color swatches that should exist alongside code, but are not code in of themselves. They should be bundled as part of the final binary, and referenced in code, but are treated like a box you pull from the shelf.

I experimented with the API, and finally came up with something that is straightforward, yet highly extendable: the idea of an IconSet. This is a PORO that:

Encapsulates the process of returning an IconComponent instance.
Has a set of easily accessible presets for how an icon should be rendered.
Provides helper methods to render specific icons based on intention/purpose rather than the specific icon
Icons can be aliased, replaced, segmented using subclassing.

# app/lib/practical_views/icon_set.rb
class PracticalViews::IconSet
  IconDefinition = Data.define(:method_name, :icon_name, :preset)

  Preset = Data.define(:family, :variant)

  PRESETS = {
    brand: Preset.new(family: :brands, variant: nil),
    duotone: Preset.new(family: :duotone, variant: :solid),
    regular: Preset.new(family: :classic, variant: :regular),
    solid: Preset.new(family: :solid, variant: nil),
    kit: Preset.new(family: :kit, variant: nil)
  }.freeze

  def self.presets
    PRESETS
  end

  def self.icon(**options)
    PracticalViews::IconComponent.new(**options)
  end

  presets.keys.each do |label|
    define_singleton_method(:"#{label}_icon") do |**options|
      preset = presets.fetch(label)
      return icon(**options.merge(family: preset.family, variant: preset.variant))
    end
  end

  def self.define_icons(icon_definitions:)
    icon_definitions.each do |icon_definition|
      define_singleton_method(icon_definition.method_name) do
        preset = presets.fetch(icon_definition.preset.to_sym)
        return icon(
          family: preset.family,
          variant: preset.variant,
          name: icon_definition.icon_name
        )
      end
    end
  end

  define_icons(icon_definitions: [
    IconDefinition.new(method_name: :user_icon, icon_name: :user, preset: :duotone),
    IconDefinition.new(method_name: :save_icon, icon_name: :"floppy-disk", preset: :duotone),
    IconDefinition.new(method_name: :filters_icon, icon_name: :filters, preset: :duotone),
  …
]

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/lib/practical_views/icon_set.rb

Dispatcher inherits from this framework-level IconSet (which will be common across all apps), to provide an ApplicationIconSet

# app/lib/application_icon_set.rb

class ApplicationIconSet < PracticalViews::IconSet
  define_icons(icon_definitions: [
    IconDefinition.new(method_name: :job_icon, icon_name: :"house-building", preset: :duotone),
    # ...
  ])

  def self.offsite_icon = organization_icon
  def self.edit_onsite_icon = onsite_icon

  def self.job_status_icon(status:)
    case status.to_sym
    when :active
      active_icon
    when :archived
      archived_icon
    end
  end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/main/app/lib/application_icon_set.rb

To streamline using it, the ApplicationHelper and ApplicationComponent have an icon_set method that returns the class:

module ApplicationHelper
  include PracticalViews::ElementHelper

  def icon_set
    ApplicationIconSet
  end
  # …
end


class ApplicationComponent < PracticalViews::BaseComponent
  delegate :icon_set, to: :helpers
end


Now, rendering an icon is as simple as:

~~~erb
<%= render icon_set.user_icon %>

And because we return an instance of the IconComponent, we can do things like pass it along to another ViewComponent, or as part of the flash hash to be serialized for rendering a Toast component:

<%= f.input_component(:name) do |component|
  component.with_label {
    f.field_title(icon: icon_set.user_name_icon, title: "Name")
  }

# app/views/components/practical_views/flash_messages_component.rb
def render_toast(color_variant:, data:, default_icon:)
  return nil if data.nil?

  case data
  when String
    message = data
    icon = default_icon
  when Hash
    data = data.with_indifferent_access
    message = data[:message]
    icon = data[:icon]
  end


  component = PracticalViews::ToastComponent.new(color_variant: color_variant)

  render component do |component|
    if icon.present? && icon.is_a?(Hash)
      icon = PracticalViews::IconComponent.new(**icon.to_h.symbolize_keys)
      component.with_icon do
        render icon
      end
    end

    message
  end
end

https://github.com/practical-computer/flip-on-the-awesome-snapshot/blob/2721248473498c3bcd8e71a8fe14ae6bcc7ca4c6/app/views/components/practical_views/flash_messages_component.rb#L3

Running the test suite against both UIs

Once you’ve gotten all the views ported over, you can now start using your test suite to test against both versions of the UI.

The easiest way to handle this is to have the test suite check for an environment variable, which sets the feature flag globally before each test run:

# test/test_helper.rb
module WebAwesomeTest
  def self.web_awesome?
    ActiveRecord::Type::Boolean.new.cast(ENV.fetch("WEB_AWESOME"){ false })
  end
end

# …
setup do
  if WebAwesomeTest.web_awesome?
    Flipper.enable(:web_awesome)
  end
end

# …
class ActionDispatch::IntegrationTest
  if WebAwesomeTest.web_awesome?
    include PatchedFlashAssertions
  else
    include PracticalFramework::TestHelpers::FlashAssertions
  end
# …

You can then set up your CI to run the tests for both versions of the UI, and make patches as needed to adjust the test behavior. In short: you should take the same approach as dual-booting Rails versions to incrementally upgrade.

Relevant files:

Tips and other items I couldn’t find a place for

ViewComponent Tips

In no particular order, here are some things I found helpful as I wrote out the ViewComponents for my framework, and Dispatcher in particular.

ViewComponent configuration

Below is the configuration I used for ViewComponent:

# config/application.rb
config.view_component.view_component_path = "app/views/components"
config.eager_load_paths << Rails.root.join("app/views/components")
config.view_component.generate.preview = true
config.view_component.capture_compatibility_patch_enabled = true
config.view_component.default_preview_layout = "component_preview"
config.view_component.preview_controller = "CustomViewComponentsController"

I want my view components to be logically structured with the rest of the view code, the compatibility patch needs to be enabled, the generators should always encourage me to fill out the previews, and you need custom preview layouts & controllers for any non-trivial app.

Forms should be components, and live in the `Forms::` namespace

Making ViewComponents to encapsulate your forms treats them with the same level of code quality you give to the backend code. It also helps you:

Prototype a form using Lookbook.
DRY up your forms with your standard OOP tool belt.
Scan through your application when debugging or getting oriented with a particular feature.

It also helps keep your views lighter because forms generate a lot of specialized markup. You’ve likely taken a similar approach with form partials in your existing code, but ViewComponents are better encapsulations of the complexity.

Don’t over-generalize!

A big problem with building component libraries is the desire to over-generalize. It works great in demos (and that’s how folks tend to show off the libraries), but it ends up being a ton of maintenance overhead and frankly annoying code to deal with.

If you have something that needs to be peppered everywhere, like “Icon + Text”, that should be a helper method. You don’t need a full component for it because that just clutters your actual view code. My first pass at standardizing “Icon + Text” was actually a ViewComponent, but for terseness & simplicity, I refactored it back to a standard Helper method:

def icon_text(icon:, text:, options: {})
    tag.span(**mix({class: "wa-flank wa-gap-3xs icon-text"}, options)) {
      safe_join([
        (render icon),
        tag.span(text)
      ])
    }
  end

ViewComponents are a powerful tool for abstracting and cleaning up view code, but don’t abuse them! Helpers are just a good a tool for small cases.

Define your own abstraction layer, based on the intentions that make sense to you

If you’re using a good frontend component library, it already has a comprehensive language to abstract away problems for you. Rather than trying to map that 1:1 with your ViewComponents, you should instead define the abstractions that make sense for you.

It’s better to define your own ergonomics, and let the frontend framework grow and adapt as needed. You’ll be able to adapt its changes to your own needs, finding the right translation between each layer, without muddying up the rest of the logic in your application layer.

Time to `mix` and `grab` from Phlex

Phlex has two great helpers, mix and grab; whose source is easily available. I’d highly recommend reading their documentation, and adding them to your project.

Slots over Subclasses, generally

One of ViewComponent’s power features is slots. They allow you to customize behavior for one-off/specialized cases, without needing to go through the hassle of managing subclasses or generalizing a component.

We went over this some with the InputComponent, but let’s also look at the Organization::NoteComponent:

# app/views/components/v2/organization/note_component.rb

class V2::Organization::NoteComponent < ApplicationComponent
  renders_one :resource_link
  renders_one :actions
  attr_accessor :note

  def initialize(note:)
    @note = note
  end
end

# app/views/components/v2/organization/note_component.html.erb
<wa-card with-footer class="card-footer note" id="<%= dom_id(note) %>">
  <section class="wa-stack wa-gap-0 tiptap-document">
    <%= render PracticalViews::TiptapDocumentComponent.new(document: note.tiptap_document) %>
  </section>


  <footer slot="footer" class="wa-stack">
    <section class="wa-split">
      <section class="wa-cluster">
        <%= render UserNameComponent.new(user: note.original_author) %>
        <% if resource_link? %>
          <section><%= resource_link %></section>
        <% end %>
      </section>
      <section class="wa-stack wa-gap-0 wa-size-s">
        <span>written <%= render PracticalViews::RelativeTimeComponent.new(time: note.created_at) %></span>
        <% if note.created_at != note.updated_at %>
          <em>updated <%= render PracticalViews::RelativeTimeComponent.new(time: note.updated_at) %></em>
        <% end %>
      </section>
    </section>

    <% if actions? %>
      <section>
        <%= actions %>
      </section>
    <% end %>
  </footer>
</wa-card>

I want to optionally add actions (such as editing/deleting a note), or a link to the resource the note is tied to. Rather than creating a myriad of subclasses (a maintenance nightmare), I can define the slots right where they’re needed in the view code:

# app/views/components/organization/onsite/notes_component.html.erb
<section class="wa-stack">
  <h3><%= icon_text(icon: icon_set.notes_icon, text: "Notes") %></h3>

  <section class="wa-stack" role="list">
    <% onsite.notes.chronological.each do |note| %>
      <%= render V2::Organization::NoteComponent.new(note: note) do |component| %>
        <% component.with_actions do %>
          <section class="wa-size-s wa-split">
            <%= link_to edit_organization_note_url(current_organization, note), class: "wa-button" do %>
              <%= icon_text(icon: icon_set.notes_icon, text: t("dispatcher.notes.edit_note.link_title")) %>
            <% end %>

            <%= button_to(organization_note_url(current_organization, note), method: :delete, class: 'wa-danger', data: {confirm: t("dispatcher.notes.delete_note.confirmation_message") }) do %>
              <%= icon_text(icon: icon_set.delete_note_icon, text: t("dispatcher.notes.delete_note.link_title")) %>
            <% end %>
          </section>
        <% end %>
      <% end %>
    <% end %>
  </section>

  <section class="add-note-form">
    <%= render Forms::Onsite::AddNoteFormComponent.new(form: note_form) %>
  </section>
</section>

Like with subclasses, you can easily abuse slots. But when working with ViewComponents, I’d reach for a Slot until you truly need a subclass.

Use `call` for basic components, `tag.*` helpers for complex attribute serializing

For basic components that don’t require a lot of markup, I forgo the sidecar template file in favor of building the template directly in the component class. In particular, I use the tag.* helpers here (and wherever I am writing elements that mixin hash-based attributes) to ensure proper markup.

Some examples:

# app/views/components/practical_views/form/option_label_component.rb
class PracticalViews::Form::OptionLabelComponent < PracticalViews::BaseComponent
  renders_one :title
  renders_one :description
  attr_accessor :options

  def initialize(options: {})
    self.options = options
  end


  def call
    tag.section(**mix({class: "wa-stack wa-size-s wa-gap-0"}, options)) {
      safe_join([
        tag.span(title),
        tag.small(description, class: "wa-quiet"),
      ])
    }
  end
end

# app/views/components/practical_views/navigation/breadcrumbs_component.html.erb
<%= tag.wa_breadcrumb(**finalized_options) do %>

  <% if truncate_middle? %>
    <% truncate_start.each do |crumb| %>
      <%= build_crumb(crumb: crumb) %>
    <% end %>

    <wa-breadcrumb-item>
      <wa-dropdown>
        <wa-button slot="trigger" size="small" appearance="filled" pill>
          <wa-icon label="More options" name="ellipsis" variant="solid"></wa-icon>
        </wa-button>
        <nav class="wa-stack wa-gap-xs dropdown-navigation">
          <ul class="navigation-list">
          <% truncated_items.each do |crumb| %>
            <li><%= tag.a(crumb.name, href: (crumb.current? ? nil : crumb.url)) %></li>
          <% end %>
          </ul>
        </nav>
      </wa-dropdown>
    </wa-breadcrumb-item>

    <% truncate_end.each do |crumb| %>
      <%= build_crumb(crumb: crumb) %>
    <% end %>
  <% else %>
    <% breadcrumb_trail.each do |crumb| %>
      <%= build_crumb(crumb: crumb) %>
    <% end %>
  <% end %>
<% end %>

Don’t worry about testing until everything has been ported

There will be so much in flux as the new variants & components get built out that testing at this stage is a waste of cycles. Likewise, the porting is already a massive slog, so you don’t want to introduce even more slog to that process and lose momentum

Additionally: You don’t need a preview or tests for everything

ViewComponent makes a point to emphasize previews & tests, leading you to believe that you need them for everything. However, even though I’m someone who swears by testing extensively, I think unit tests on ViewComponents are generally overkill.

Testing is a game of tradeoffs. You sacrifice sprints for overall endurance, quick code for testable code, “fun” for stability. UIs generate a lot of code, but it’s also surfaced to the user and problems are easily recognized by them.

With a good test suite, you also get decent coverage on your components because you’re already rendering them as part of the integration or system tests.

If I’m thinking of where to burn my testing & dev budgets, I’d much rather spend them on testing at other layers, or improving my development & Lookbook data via Oaken.

Aim for previews that load painlessly in Lookbook, test the truly critical components if it helps you sleep better. But don’t lose sight of shipping a better UI for people.

Fighting Boredom

Tackling a UI overhaul is a slow process, so you want to make sure to pace yourself, avoid burnout, and prevent boredom.

A fresh coat of paint

A good way to fight boredom, and test the flexibility of your components, is to swap out the theme for your frontend framework. It makes the work less tedious and makes sure you aren’t drifting too far from what the framework has defined as guidelines.

You might also find a new theme that works better for your app as it gets closer to release!

Switch to other projects

If you get tired of the process of porting views into components, pick up a small ticket to avoid falling asleep at the wheel.

Keep getting PRs merged in

Having the code live on main avoids the feeling of toiling away on something that won’t see the light of day. If it’s on main, other developers can see it and give feedback. You can show it off to customers in sneak peeks, and get everyone excited about the fresh coat of paint.

Fixing the Rails 7+ networking stack

2024-08-10T00:00:00Z

Fixing the Rails 7+ networking stack

Let’s talk networking stacks. Which, I know, boring, but it’s foundational!

The problem and general stack

I want Little CRM to be as resilient as possible, which means making it progressively enhance through as much of the gamut as possible:

No JS loaded.
JS is partially loaded (but broken).
JS is loaded, but Websockets are busted.
Websockets are functional, giving us real-time updates.

Given this, the network stack needs the following:

Support for standard HTTP request/responses, even if they’re not ideal. Progressive enhancement is about allowing people to keep using your app if things are non-ideal (but still functional), not a 1:1 replication top-to-bottom.
A sensible client-side API for handling fetch/AJAX-based requests.
A lightweight real-time update layer using Websockets, as minimally impactful as possible in both client-side code & the app’s dependence on it.

Generally speaking, the stack looks like this:

Write the page markup semantically using native form elements & links.
Use Mrujs to progressively enhance the forms & links that should use fetch/AJAX requests.
Take advantage of Rails’ respond_to method to provide both ideal (fetch/AJAX) and fallback HTML responses with minimal code duplication.
Use CableReady as the response protocol for fetch/AJAX requests (using CableCar), while also using it to broadcast changes using the same payload for both.
Adding light event handlers in the browser to handle edge cases such as double-prepending & augmenting form submission events to autofocus & reset forms. Thanks to the beauty of Mrujs & CableReady’s designs, only 3 were needed!

The first question is, “Why not Hotwire/Turbo?”. I mean, this is a Rails app, after all!

Turbo adds excessive complexity and reimplements the browser

After using Hotwire/Turbo in its various iterations, observing folks talk about it, and looking at the larger context of the library, the following problems made that not a viable option here.

It reimplements the core of the browser

Turbo relies heavily on DOM morphing, a core tenant being “write your server-rendered pages and let Turbo morph the DOM & browser history for SPA-like responsiveness”. This introduces major & frustrating points of failure for two of the most foundational parts of a web browser.

Trying to sidestep how the browser handles page loading and its history, using morphing and heavily mucking with the History API, introduces a ton of gotchas. When you factor in:

Browser caching
HTTP2/3
Network speeds
The complexity of browser engines

I think it’s better to have your standard request/response flow-either as standard page navigation or by returning JSON that some lightweight JS handlers can use to update some of the existing DOM. Instead, the Turbo approach tries to programmatically diff the changes and morph the page to match what has changed, then change the browser’s history. It’s the same class of problem as a virtual DOM. Even if you’re using something like morphdom, the principle of how it operates is the same.

While you can opt out of these behaviors, you have to explicitly do so with a boatload of meta tags, configuration, and remembering to do so. Turbo wants to do all this work; it thinks this is the way to handle behavior. Which I disagree with because most of the conversations around Turbo I see outside CodePens & simple examples are seasoned programmers asking why it’s not working as expected. And if the default behavior of a framework as critical as your frontend stack causes that, then maybe its approach is fundamentally flawed.

CableReady does have DOM morphing and browser history manipulation, but they are opt-in. It’s clear when those behaviors occur because you choose to enable them. You only write code for the behaviors you want—not to rip out the behaviors that cause problems.

Turbo Streams are not an easily grokable/adjustable protocol

Turbo Streams are how Turbo allows you to send incremental changes as part of remote form submissions, but they’re difficult to use outside of the very basic cases.

For those who aren’t familiar with them, this is an example of Turbo Streams from the docs:

<turbo-stream action="append" target="messages">
  <template>
    <div id="message_1">
      This div will be appended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="prepend" target="messages">
  <template>
    <div id="message_1">
      This div will be prepended to the element with the DOM ID "messages".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="replace" target="message_1">
  <template>
    <div id="message_1">
      This div will replace the existing element with the DOM ID "message_1".
    </div>
  </template>
</turbo-stream>

<turbo-stream action="after" targets="input.invalid_field">
  <template>
    <!-- The contents of this template will be added after the
    all elements that match "inputs.invalid_field". -->
    <span>Incorrect</span>
  </template>
</turbo-stream>

In essence, there are a series of custom elements that encapsulate the changes to the DOM & browser you want to perform.

I can see how you arrive at this API design! It’s not awful, but it could be so much easier & extendable.

Like CableCar, the protocol for CableReady operations.

Let’s look at a similar payload of CableCar operations:

[
  {
    "selector": "#messages",
    "html": "<div id=\"message_1\">This div will be appended to the element with the DOM ID \"messages\".</div>",
    "operation": "append"
  },
  {
    "selector": "#messages",
    "html": "<div id=\"message_1\">This div will be prepended to the element with the DOM ID \"messages\".</div>",
    "operation": "prepend"
  },
  {
    "selector": "#message_1",
    "html": "<div id=\"message_1\">This div will replace the existing element with the DOM ID \"message_1\".</div>",
    "operation": "replace"
  },
  {
    "selector": "input.invalid_field",
    "select_all": true,
    "position": "afterend",
    "html": "<span>Incorrect</span>",
    "operation": "insertAdjacentHtml"
  }
]

See the code that generates this JSON

cable_car.append(
  selector: "#messages",
  html: render_to_string(partial: "..."", formats: [:html])
)

cable_car.prepend(
  selector: "#messages",
  html: render_to_string(partial: "..."", formats: [:html])
)

cable_car.replace(
  selector: "#message_1",
  html: render_to_string(partial: "..."", formats: [:html])
)

cable_car.insert_adjacent_html(
  selector: 'input.invalid_field',
  select_all: true,
  position: 'afterend',
  html: '<span>Incorrect</span>'
)

It’s easily understandable; you can explain it in a sentence: there is a JSON array of operations, and you can augment the default behavior with extra JSON data.

Because it’s an extremely simple protocol, it can be reused across transmission mechanisms with minimal cognitive overhead. In my case, I’m using:

Mrujs’s CableCar plugin
CableReady’s default ActionCable interface
A custom channel I’ve defined

All use the same protocol, avoiding duplicate code & juggling different mental models.

I can’t emphasize enough how useful this is: one protocol, easily understandable, flexible enough to be incorporated into a wide variety of contexts.

One protocol, easily understandable, flexible enough to be incorporated into a wide variety of contexts.

Coming back to that point about augmenting the protocol, I have a concrete example of this: prepend only if a selector is missing.

The use case is straightforward:

We want people to be able to post to a timeline.
We want updates to show up immediately on the new timeline.
We want any real-time updates for new posts added by others or in another tab.

A demo showing off realtime posts via CableCar and CableReady, using the same JSON payload for both

Here's the Microposts Controller

# app/controllers/organizations/microposts_controller.rb
class Organizations::MicropostsController < Organizations::BaseController
  include CableReady::Broadcaster
  include TimelineEdgeContextLoading
  include TimelineEntryCableCar
  include FlashMessagesCableCar
  # ...

  def create
    @form = Organization::MicropostForm.new(organization_micropost_params)
    @form.save!

    message = t('little_crm.microposts.created_message')
    flash[:success] = flash_success_with_icon(message: message, icon: helpers.micropost_icon)

    organization_micropost = @form.micropost
    # Helper method that determines what URL we should redirect to, centralized for easier testing
    redirect_url = helpers.url_for_root_context(root_context: @form.creation_postable,
                                                options: {autofocus_micropost: true},
                                                fallback: organization_micropost_url(current_organization,
                                                                                     organization_micropost)
                                               )

    respond_to do |format|
      format.html { redirect_to redirect_url }
      format.cable_ready do
        render_flash_messages_to_cable_car_and_clear

        edge = @form.micropost&.timeline_node&.outward_edges&.first
        if edge.present?
          edge_context = Timeline::EdgeContext.new(edge: edge, root_context: @form.creation_postable)
          cable_car_add_timeline_entry(timeline_edge_context: edge_context)
        end

        render(cable_ready: cable_car)
      end
    end
  rescue ActiveRecord::RecordInvalid, ActiveModel::ValidationError
    default_respond_to_model_validation_error(html_action: :new, model: @form)
  end

  # ...

  # Only allow a list of trusted parameters through.
  def organization_micropost_params
    params.fetch(:organization_micropost).permit(
      :content
    ).merge(
      current_user: current_user,
      current_organization: current_organization,
      creation_postable: Organization::Micropost::Postable.fetch_from_sgid(sgid: params.dig(:organization_micropost,
                                                                                            :creation_postable))
    )
  end
end

The micropost form

# app/views/organizations/microposts/_form.html.erb
<%# locals: (form:, creation_postable: nil, timeline_edge_context: nil) -%>
<%# The `creation_postable` is set to the organization in this example, since we're posting on the Organization's timeline %>
<% input_id = dom_id(form, :content_text_input) %>
<%= application_form_with(model: form,
                           url: url_for([form.micropost, organization_id: current_organization]),
                           data: { reset_on_ajax_success: true, focus_on_ajax_success: id_selector(input_id) })
                          do |f| %>
  <!-- ... -->
  <% if creation_postable.present? %>
    <%= f.hidden_field :creation_postable, value: creation_postable.postable_sgid %>
  <% end %>
<% end %>

And some of the concerns to DRY up the code

# app/controllers/concerns/flash_messages_cable_car.rb
module FlashMessagesCableCar
  extend ActiveSupport::Concern

  def render_flash_messages_to_cable_car_and_clear
    cable_car.outer_html(
      selector: ".notification-messages",
      html: render_to_string(partial: "/layouts/snippets/flash_messages", formats: [:html])
    )

    flash.delete(:success)
    flash.delete(:alert)
    flash.delete(:notice)
  end
end

# app/controllers/concerns/timeline_entry_cable_car.rb
module TimelineEntryCableCar
  extend ActiveSupport::Concern
  # ...
  def cable_car_add_timeline_entry(timeline_edge_context:)
    cable_car.prepend(
      **CableCarAndBroadcast::Timeline.prepend_new_edge(timeline_edge_context: timeline_edge_context)
    )
  end
end

The concern that prepares the CableCar response while also broadcasting the same payload

# app/broadcasters/cable_car_and_broadcast/timeline.rb
module CableCarAndBroadcast::Timeline
  extend CableReady::Broadcaster

  def self.helpers
    ApplicationController.helpers
  end

  def self.prepend_new_edge(timeline_edge_context:)
    html_string = CableCar::TimelineEntryController.render_new_timeline_entry(
      timeline_edge_context: timeline_edge_context
    )

    arguments = {
      existing_selector: helpers.id_selector(timeline_edge_context.to_gid_param),
      selector: helpers.id_selector(helpers.timeline_dom_id(root_context: timeline_edge_context.root_context)),
      html: html_string
    }

    cableready_stream = cable_ready[TimelineStreamChannel]
    cableready_stream.prepend(**arguments)
                     .broadcast_to(timeline_edge_context.stream)
    cableready_stream.broadcast_to(timeline_edge_context.organization_stream)

    return arguments
  end

  # ...
end

# I kept this as a controller so that the mental modeling of Controller => View rendering is retained
# app/controllers/cable_car/timeline_entry_controller.rb
class CableCar::TimelineEntryController < ApplicationController
 def self.render_new_timeline_entry(timeline_edge_context:)
    renderer.render(
      partial: "/timelines/entry",
      locals: {
        edge: timeline_edge_context.edge,
        root_context: timeline_edge_context.root_context
      },
      formats: [:html],
    )
 end
  # ...
end

We use the same payload to prepend the post in both the AJAX response and the ActionCable broadcast, giving us consistent updates and DRY code. But a double posting problem presented itself.

To recap the problem:

You can post on a timeline, which is done via a fetch request.
That returns a CableCar set of responses, prepending the post to the timeline.
But since we also want the timeline to receive real-time updates, the browser will also get the broadcasted update since it’s subscribed to the timeline’s broadcast channel.

Notice how Browser 1 is going to receive both the HTTP response and the websockets broadcast.

So, we need to throw away the prepend operation that comes last (assuming both arrive, which you can’t assume!)

Because CableReady is well-designed, it has events for each stage of the lifecycle for each operation. And because it also gives you the flexibility to add arbitrary data for existing operations, this became a basic fix: a global utility function that is hooked into an event listener:

export async function throwAwayExistingCableReadyPrependEventHandler(event) {
  const existingSelector = event?.detail?.existingSelector
  if(!existingSelector){return}
  if(!document.querySelector(existingSelector)){ return }
  event.detail.cancel = true
}
// ...
import { throwAwayExistingCableReadyPrependEventHandler } from 'practical-framework'
// ...
document.addEventListener(`cable-ready:before-prepend`, throwAwayExistingCableReadyPrependEventHandler)

That’s all it took! And the mental model is straightforward.

Operations are self-contained, so they operate independently.
Because they’re a common datatype (an array of objects), the idea of a series of lifecycle events that are dispatched is a natural extension.
Because they are that common, almost primitive datatype, event handlers can easily inspect their details and, well, handle the event!

So with that sprinkling of code, I’ve got real-time updates that can reuse the exact same payloads as the AJAX request/response that is tried and true.

Designing plain HTML fallbacks

Making sure an app is functional when a regular HTTP request is made is a core tenant of progressive enhancement.

We’ve all run into it before—you click a button or submit a form, and either:

Nothing seems to happen.
You get a weird JSON payload.

It’s immensely frustrating and a solvable problem!! But at its core, folks are still not designing well enough for the underlying HTML responses.

This comes down to folks throwing up their hands when it comes to progressive enhancement. If a request is made via AJAX, teams don’t make an HTML backup. Developers don’t think about how to design to get “close enough” with just plain requests.

I want to highlight how you can design good HTTP fallbacks, even in a complex set of behaviors.

To reiterate the flows:

People can post directly to a timeline when viewing it, and they should be able to quickly Post Through It.
They can also view a post-seeing metadata and connections for it.
Finally, people can edit the post, either directly from the timeline or when viewing it via the permalink.

A few steps above your standard CRUD responses! Especially when you think about how to get the user efficiently back to where they want to be. But it is solvable, and Rails helps you solve it. Let’s look at the code:

Here's the Microposts Controller again, this time focused on show/edit/update and creation errors

# app/controllers/organizations/microposts_controller.rb
class Organizations::MicropostsController < Organizations::BaseController
  include CableReady::Broadcaster
  include TimelineEdgeContextLoading
  include TimelineEntryCableCar
  include FlashMessagesCableCar
  # ...

  def show
    breadcrumb(t('loaf.breadcrumbs.organization_micropost'),
               organization_micropost_url(current_organization, @organization_micropost)
              )

    respond_to do |format|
      format.html
      format.cable_ready do
        render_micropost_show_in_container(organization_micropost: @organization_micropost)
        render(cable_ready: cable_car)
      end
    end
  end

  def new
    @creation_postable = Organization::Micropost::Postable.fetch_from_sgid(sgid: params[:postable_sgid])
    breadcrumb :new_organization_micropost,
               postable_new_organization_micropost_url(current_organization, params[:postable_sgid])
    @form = Organization::MicropostForm.new(
      current_organization: current_organization,
      current_user: current_user
    )
  end

  def edit
    breadcrumb(t('loaf.breadcrumbs.edit_organization_micropost'),
               edit_organization_micropost_url(current_organization, @organization_micropost)
              )
    @form = Organization::MicropostForm.new(
      micropost: @organization_micropost,
      current_organization: current_organization,
      current_user: current_user
    )

    respond_to do |format|
      format.html
      format.cable_ready do
        cable_car.outer_html(
          selector: "[data-micropost-id='#{@organization_micropost.id}']",
          html: render_to_string(partial: "form",
                                 locals: { form: @form, timeline_edge_context: @timeline_edge_context },
                                 formats: [:html]
                                )
        )

        render(cable_ready: cable_car)
      end
    end
  end

  def create
    # ...
  rescue ActiveRecord::RecordInvalid, ActiveModel::ValidationError
    default_respond_to_model_validation_error(html_action: :new, model: @form)
  end

  def update
    @form = Organization::MicropostForm.new(organization_micropost_params.merge(
      micropost: @organization_micropost
    ))
    @form.save!

    organization_micropost = @form.micropost

    updated_message = t('little_crm.microposts.updated_message')
    flash[:success] = flash_success_with_icon(message: updated_message, icon: helpers.micropost_icon)

    respond_to do |format|
      format.html { redirect_to organization_micropost_url(current_organization, organization_micropost) }
      format.cable_ready do
        render_flash_messages_to_cable_car_and_clear
        render_micropost_cable_ready_update
        render(cable_ready: cable_car)
      end
    end
  rescue ActiveRecord::RecordInvalid, ActiveModel::ValidationError
    default_respond_to_model_validation_error(html_action: :edit, model: @form)
  end

  # ...

  private

  def render_micropost_show_in_container(organization_micropost:)
    cable_car.inner_html(
      selector: "[data-micropost-details-container]",
      html: render_to_string(partial: "organizations/microposts/show/post",
                             locals: { organization_micropost: organization_micropost },
                             formats: [:html]
                            )
    )
  end

  def render_micropost_cable_ready_update
    if @timeline_edge_context.present?
      cable_car_replace_timeline_entry(timeline_edge_context: @timeline_edge_context)
    else
      render_micropost_show_in_container(organization_micropost: @organization_micropost)
    end
  end
  # ...
end

The Framework-level concern to handle errors in a form submission

module PracticalFramework::Controllers::ErrorResponse
  extend ActiveSupport::Concern

  def render_json_error(format:, model:)
    format.json do
      # Renders a custom payload that client-side JS can handle.
      # Likely will get refactored to use CableCar, this is pre-CableCar code
      errors = PracticalFramework::FormBuilders::Base.build_error_json(model: model, helpers: helpers)
      yield(errors) if block_given?
      render json: errors, status: :bad_request
    end
  end

  def render_html_error(action:, format:)
    format.html do
      yield  if block_given?
      render action, status: :bad_request
    end
  end

  def default_respond_to_model_validation_error(html_action:, model:)
    respond_to do |format|
      render_json_error(format: format, model: model)
      render_html_error(action: html_action, format: format)
    end
  end
end

The TimelineEntryCableCar concern again

# app/controllers/concerns/timeline_entry_cable_car.rb
module TimelineEntryCableCar
  extend ActiveSupport::Concern
  # ...
  def cable_car_replace_timeline_entry(timeline_edge_context:)
    cable_car.outer_html(
      **CableCarAndBroadcast::Timeline.replace_timeline_entry(timeline_edge_context: timeline_edge_context)
    )
  end
end

CableCarAndBroadcast::Timeline, this time for replacing a micropost

# app/broadcasters/cable_car_and_broadcast/timeline.rb
module CableCarAndBroadcast::Timeline
  extend CableReady::Broadcaster

  def self.helpers
    ApplicationController.helpers
  end
  # ...
  def self.replace_timeline_entry(timeline_edge_context:)
    html_string = CableCar::TimelineEntryController.render_timeline_entry_component(
      timeline_edge_context: timeline_edge_context
    )

    arguments = {
      selector: helpers.id_selector(timeline_edge_context.to_gid_param),
      html: html_string
    }

    cableready_stream = cable_ready[TimelineStreamChannel]
    cableready_stream.outer_html(**arguments)
                     .broadcast_to(timeline_edge_context.stream)
    cableready_stream.broadcast_to(timeline_edge_context.organization_stream)

    return arguments
  end
end

# app/controllers/cable_car/timeline_entry_controller.rb
class CableCar::TimelineEntryController < ApplicationController
  # ...
  def self.render_timeline_entry_component(timeline_edge_context:)
    renderer.render(
      partial: "timeline_entry",
      locals: {
        timeline_edge_context: timeline_edge_context,
      },
      formats: [:html],
    )
 end
end

The micropost form

# app/views/organizations/microposts/_form.html.erb
<%# locals: (form:, creation_postable: nil, timeline_edge_context: nil) -%>
<% input_id = dom_id(form, :content_text_input) %>
<%= application_form_with(model: form,
                           url: url_for([form.micropost, organization_id: current_organization]),
                           data: { reset_on_ajax_success: true, focus_on_ajax_success: id_selector(input_id) })
                          do |f| %>
  <!-- ... -->
  <%= f.fieldset do %>
    <!-- ... -->
    <%= f.input_wrapper do %>
      <%= f.micropost_field(:content, autofocus: params.has_key?(:autofocus_micropost), id: input_id, #...) %>
      <section class="cluster-compact justify-space-between">
        <%= f.field_errors :content %>
        <!-- ... -->
        <% end %>
      </section>
    <% end %>

    <%= f.fallback_error_section(options: {id: dom_id(form, :generic_errors)}) %>

    <section class="cluster-compact">
      <%= render PracticalFramework::Components::StandardButton.new(
        title: t("little_crm.microposts.form.submit_button_title"),
        html_options: {data: {disable: true}}) #...
      %>

      <%# The timeline_edge_context is the record that's used to show the timeline, the timeline edges reference microposts, but
           are a separate set of models to separate their concerns -%>
      <% if timeline_edge_context.present? %>
        <%= micropost_cancel_edit_button(formaction: organization_timeline_edge_context_url(edge_context_gid: timeline_edge_context.to_gid)) %>
        <%= hidden_field_tag :edge_context_gid, timeline_edge_context.to_gid %>
      <% elsif form.persisted? %>
        <%# Show the "Nevermind" button when editing a micropost via its permalink %> 
        <%= micropost_cancel_edit_button(formaction: url_for([form.micropost, organization_id: current_organization])) %>
      <% end %>
    </section>
  <% end %>

  <!-- ... -->
<% end %>

A big thing to aim for with your fail-safe fallback is to get something that mostly works and gets the person near the right path. It’s obviously not ideal, but it is there, and it works in an emergency.

Another important note is how errors are handled. This is something I’ve chipped away at for months because we’ve lost the institutional knowledge on how to best do this (and no one’s really codified it).

The controller actions rescue any validation errors that are raised (I’m a huge proponent of using the bang! methods for creation/saving/validation so the control flow is easier). These actions can respond to both:

A request that accepts JSON data. In this case, the errors are serialized into a format that the client-side JS can use to update the form’s validation state using the constraint validation APIs the browser provides and insert error messages.
A standard request that accepts HTML. In this case, we re-render the form that currently has the errors, which then renders the errors as part of its markup.

Note that the HTML fallback does not need to be perfect. We just need to make sure the user isn’t unnecessarily blocked.

Let’s look at what happens if there is an error when someone is submitting a post on the organization’s timeline.

When JS is working, the errors are rendered inline. When JS is not working, the browser is redirected to a basic fallback page that renders the form.

Demos showing off how the microposts form works even when JS is disabled

Again, this is not the ideal experience. But it is an experience that allows the person to move forward, do what they need to do.

Admittedly, there are some cases where you do need JS. A concrete example is Stripe’s Payment Elements. In my mind, in those cases, progressive enhancement is rendering an error message directly on the page— something like:

Sorry! We ran into an issue rendering the payment element here. Please try reloading the page, and contact support if you still run into issues!

That’s progressive enhancement because the user knows what happened, what’s going on, and how to resolve it. And it’s infinitely better than a page that’s mysteriously busted or a form that won’t submit and shows no error messages.

You can imagine the way I buried my head in my hands when I demoed this to an acquaintance, and their shitpost response was:

“I didn’t realize you could make usable websites without Javascript”

(Side note: this was the impetus for one of my best shitposts, IMO)

UJS is still a fantastic design, and you should be using Mrujs

A quick history primer: UJS stands for “Unobtrusive Javascript”, and Wikipedia has a great summary & overall page:

Unobtrusive JavaScript is a general approach to the use of client-side JavaScript in web pages so that if JavaScript features are partially or fully absent in a user’s web browser, then the user notices as little as possible any lack of the web page’s JavaScript functionality.

Rails 6 shipped with a library called, shockingly, UJS. Its design was relatively small, but immensely powerful and flexible. By using data attributes & event handlers, you could augment your markup to perform actions if Javascript was enabled. Basic stuff that every web app wants, such as:

Submitting forms via AJAX.
Presenting confirmation dialogs.
Enabling/disabling elements (and changing the inner content if needed).

While UJS unceremoniously got dumped by DHH, Konnor Rogers has written a modern version, Mrujs, and you should absolutely be using it. The UJS design is evergreen because it’s lightweight and leans into the browser’s strengths.

UJS, largely speaking, is focused on augmentation. It operates on the assumption that Javascript will not be available, and that you might not need it in the first place. Which is becoming increasingly true! Look at all the stuff we’ve gotten in Baseline! Unlike Turbo/Hotwire/React/etc., UJS is designed to take up as little space as possible, defer to the browser, and automatically have its foot out the exit door when it knows it’s not needed. Why would you waste bandwidth on a framework that browsers don’t need?

The other browser strength that UJS rests on is heavy usage of event dispatching. The browser is a machine that spits out events and can handle those events; it’s really good at it, too! The original UJS library wasn’t as good as I’d like about its event handling (or even documenting it), but Mrujs is.

Mrujs event handlers to reset and autofocus a form

export async function resetOnAjaxSuccessEvent(event) {
  const target = event.target
  if(!target?.dataset?.resetOnAjaxSuccess){ return }
  target.reset()
}

export async function focusOnAjaxSuccessEvent(event) {
  const target = event.target
  const focusTargetSelector = target?.dataset?.focusOnAjaxSuccess
  if(!focusTargetSelector){ return }

  const focusTarget = document.querySelector(focusTargetSelector)
  focusTarget?.focus()
}

// ...
import { resetOnAjaxSuccessEvent } from 'practical-framework'
import { focusOnAjaxSuccessEvent } from 'practical-framework'

document.addEventListener(`ajax:success`, resetOnAjaxSuccessEvent)
document.addEventListener(`ajax:success`, focusOnAjaxSuccessEvent)

Other bits & bobs

CableReady’s documentation is pretty comprehensive. Certainly more comprehensive than the docs for most new Rails features since Rails 5. I don’t necessarily like the tone, but I’ll take memeified docs over no docs any day of the week.

One argument I’ve heard against CableCar is that sometimes the API doesn’t feel very Rails-like. I haven’t found that to be a significant deterrent, and that could be solved with refactoring/helpers/magic. Also, there are a few counterarguments:

One ethos of Rails is to use sensible, easily understandable behavior in 90% of cases. CableCar is a protocol that does that.
Rails also advocates for “using boring technology/patterns.” CableReady/CableCar are infinitely more boring than Turbo/Hotwire. 👀
Browsers are complex systems, and using their universal mechanisms allows more developers to work on Rails apps and encourages the growth of the ecosystem. Much more than a bespoke frontend framework.

Musing: How much of an app really needs to be real-time?

As I was building this out, I conducted a very unscientific poll. The results aren’t even close to being statistically significant, but I still think they’re interesting!

From these results, my experience working & maintaining apps, and hearing what folks struggle with in their apps; the vibe is that going real-time-first only happens in demos & simple code.

I also asked Konnor Rogers, who has extensive frontend knowledge and is part of the Web Awesome team! And he agreed with my suspicions:

🌶️ the more I think about morphing, the more I think it's the wrong tool for the job.

It's easy to end up with stale nodes, nodes that have event listeners they shouldn't, unless your server is recording every possible client interaction, it'll still wipe away client state. https://t.co/tJbuxLpkmb
— Konnor Rogers (@RogersKonnor) August 5, 2024

I've written like 3 responses to this, but char limit is screwing me.

morphing / preserving nodes has a place. Implicitly doing so is a super easy footgun that's hard to debug. View transitions should help solve this problem in the future. Explicit marking makes debugging easier
— Konnor Rogers (@RogersKonnor) August 5, 2024

There's the other problem of it's impossible to stream HTML with morphing. (Well not impossible, but way more error prone, and behavior is bizarre)

Turbo also requires full HTML responses before it can render a new page, leading to additional "slowness" if not cached
— Konnor Rogers (@RogersKonnor) August 5, 2024

@jaffathecake has a great article from *checks notes* 8 years ago which is about Turbolinks, but still applies to Turbo.

By needing the full response before you can render, you can actually make content slower particularly on unreliable networks.https://t.co/k9wA6xkUAf
— Konnor Rogers (@RogersKonnor) August 5, 2024

Yes. It's a powerful tool with sharp edges, little documentation on the inner workings, and don't get me started on the meta tags. They feel like someone set some fucking tanagrams in front of me and was like "figure out the correct combination to fit your use case"
— Konnor Rogers (@RogersKonnor) August 5, 2024

my thoughts are very few features need realtime / reactive.

HTTP requests / responses cycles are well understood. Have great caching, work well with load balancing etc.

Realtime / reactive has an entirely different set of problems. You probably want optimistic updates, which means some kind of CRDT backing mechanism. Youll probably want local first which usually means a heavy client.

And this doesnt even touch on auth / accessibility. Realtime / reactive is hard to get right.

[…]

FWIW, Turbo is like 99% request / response. So little of turbo is real time / reactive. It’s almost entirely HTTP and like a tiny bit of web sockets for model broadcasts

[…]

where I think Turbo went wrong is the following:

Links should only be able to make GET requests

<turbo-stream> should be a <turbo-action>, stream is just too confusing. It makes people think they’re using a web socket when it’s really just a DOM operation

Turbo frames are clunky with managing ids. Scoped navigation as the default is equally weird.

There’s like 40 different combo of meta tags. It’s so hard to keep them all straight.

Hearing someone else with a lot more experience mirror my thoughts helps me feel confident in my claims in this post.

Thinking in terms of complexity & the mismatch between technical and user expectations; users might not actually need truly real-time updates. At Blue Ridge Ruby, Brian Childress gave a great talk about managing complexity. And the biggest takeaway I got from that is how “real-time updates” actually means “8 AM, once a day” for clients in practice. I highly recommend watching it!

Given all of this; I do believe that the best approach for the majority of apps is:

Write progressively enhanced request/responses from the ground up, with the jackpot ideal being Websocket updates and the general assumption that your JS will be broken or not fully loaded.

Which is what you get with smart controller design & abstractions, UJS/CableCar, and a sprinkling of CableReady when it matters.

We’ve wasted a lot of time reinventing solved problems—arguably worse!

I don’t want to belabor this point too long because, frankly, it’s exhausting, demoralizing, and people with more knowledge of the internal politics than I do have already covered this.

UJS is such a lightweight tool, which is the direction that’s best as browsers do more and more. It slots in nicely with other browser APIs, like Web Components, and even heavier frontend frameworks. Unfortunately, it got dumped unceremoniously for a stack that’s significantly more complex. We were too quick to throw out UJS, which still has some excellent design decisions, and CableCar’s protocol works better than Turbo Streams for updates that can be progressively enhanced.

Turbo and Hotwire were latecomers. CableReady shipped years before them, and as I’ve (hopefully) shown, it solved the same problems better. So much so that Turbo/Hotwire 8 has enlisted some CableReady maintainers to get to feature parity with CableReady.

Even if they can get there (I doubt it; the CableReady approach is much more robust), the question is: why the hell are we doing that? Why don’t we just use the better framework, even if it didn’t originate from the Rails’ core? Why not have Rails ship with it by default, or hell contribute to it? DHH has no problem jettisoning frontend approaches between major versions (he’s done so multiple times!). There’s precedent for it.

The best thing to happen to Rails was when Merb renamed itself to Rails & gave developers a proper plugin architecture. You aren’t chained to Rails’ defaults, and we can communally choose the better tools without having Rails “bless it.” Because even if they do bless a frontend framework, that’s no guarantee for success, maintenance, or growth. So I’d argue we should choose the better tool. Community consensus is also a form of standardization.

Getting your Rails dev environment ready for passkeys

2022-10-11T00:00:00Z

Getting your Rails dev environment ready for passkeys

I spent the whole day digging through WebKit bug reports & wrangling with puma-dev , but finally have a working solution.

The gist is: while Chrome, Firefox, and non-macOS implementations of WebKit support *.localhost subdomains (and register them as a Secure Context, see: This MDN article ), WebKit on macOS does not, because of underlying macOS networking APIs. There’s a whole set of bugs about it:

So your Rails development environment needs to run with HTTPS, which requires a certificate, which is a whole mess.

`puma-dev` to the Rescue

puma-dev solves the HTTPS issue elegantly, but I’ve never liked how it runs as a daemon process by default. macOS does not have good daemon support; and for execution environments as volatile as development, daemons aren’t the right answer.

Update: Arrrgf; turns out that puma-dev only listens to 127.0.0.1 when run in the foreground, so it has to run as a daemon if you need cross-device testing (such as through VMs or on mobile devices).

However, I really don’t want to lose the ability to quickly kill & reboot my development environment. Again, the problem of macOS not having good daemon support and development being too volatile of an execution environment for daemons to be practical. So I ended up writing a script that:

Force stops the puma-dev daemon
Prints out some text to help with attaching the debugger
Starts tailing puma’s daemon logs.

#!/bin/bash

set -e

echo "make sure to attach a debugger with (or alias): rdbg -A"
echo "force-stopping puma-dev"
puma-dev -stop
echo "watching puma with: tail -f ~/Library/Logs/puma-dev.log"
echo "============"
tail -f ~/Library/Logs/puma-dev.log

The ideal solution would be for puma-dev to add a flag to specify what hosts to listen on. There’s a PR for some of this, but a customizable command-line flag (like for ports) would be a great solution; since it allows for flexibility: https://github.com/puma/puma-dev/issues/306

In case it’s useful for anyone, I’ve kept my original version at the end of this post. It’s a good example of how you can hook in Ruby’s built-in debugger as part of a larger buildchain.

puma-dev has the option to run in a foreground mode. But since puma-dev doesn’t support TTY for its child processes, you lose the ability to use the built-in Ruby debugger.

Thankfully, Ruby’s built-in debugger has a special wrapper command that we can use to automatically get an optional debugger for any process spawned by puma-dev .

The commands

The command to run puma-dev in the foreground with the debugger hooks is:

rdbg --nonstop -O -c -- bundle exec puma-dev

To attach the debugger process, run:

rdbg -A

Which is…cumbersome. I prefer using an alias:

alias attachdebugger='rdbg -A'

Setup guide to prepare for passkeys in your Rails development environment

2021-10-31T00:00:00Z

I spent 4 hours debugging how to sidestep bugs with macOS’s DNS resolver, and running puma-dev in the foreground with streamlined ruby-debug support. The setup guide’s here, save yourself the agony

Writeup about Noko's new dialogs framework

2021-10-31T00:00:00Z

I just published a high-level guide on a How we rebuilt Noko’s Dialogs, migrating from an ad-hoc series of tools to a structured framework. It was an interesting challenge, applying R&D I’d been working on for the past 3 years.

Let me know what you think!

Thomas Cannon's Blog

Flip on the Awesome

Flip on the Awesome

How to read this guide

What is Dispatcher?

What is PracticalFramework? What is PracticalViews?

The Big Picture

Tools used

Flipper

ViewComponent

Web Awesome

Lookbook

Oaken

The phases of a View Layer overhaul

How to overhaul your view layer while continuing to ship features

Keep the old & new view code totally separate with view variants and different asset builds

Why ViewComponent?

The “Experimental” capture patch

Why Web Awesome?

Problem Areas, Principles, and Tactics

Avoiding the pitfalls of a UI overhaul

The scope needs to be kept strictly in check

Refinements will happen over time

Why do seasoned developers balk at componentization?

Lack of examples & techniques

Reactive frameworks poisoned the well on great ergonomics

The browser is bringing a lot more to the table

Components aren’t a panacea

Componentization beyond toy examples and tutorial blogs

Polishing an app-wide UI component

Replacing old code with native browser features

Learning more about componentization

Decouple FormBuilders with sidechained components

Overgeneralization & Inflexibility

Bad API Design

Sidechained ViewComponents

Example: Form::InputComponent

Example: Forms::LocationFieldComponent (Application-specific input component)

Sane icon management with an IconSet PORO

Running the test suite against both UIs

Tips and other items I couldn’t find a place for

ViewComponent Tips

ViewComponent configuration

Forms should be components, and live in the Forms:: namespace

Don’t over-generalize!

Define your own abstraction layer, based on the intentions that make sense to you

Time to mix and grab from Phlex

Slots over Subclasses, generally

Use call for basic components, tag.* helpers for complex attribute serializing

Don’t worry about testing until everything has been ported

Fighting Boredom

A fresh coat of paint

Switch to other projects

Keep getting PRs merged in

Fixing the Rails 7+ networking stack

Fixing the Rails 7+ networking stack

The problem and general stack

Turbo adds excessive complexity and reimplements the browser

It reimplements the core of the browser

Turbo Streams are not an easily grokable/adjustable protocol

Designing plain HTML fallbacks

UJS is still a fantastic design, and you should be using Mrujs

Other bits & bobs

Musing: How much of an app really needs to be real-time?

We’ve wasted a lot of time reinventing solved problems—arguably worse!

Getting your Rails dev environment ready for passkeys

Getting your Rails dev environment ready for passkeys

puma-dev to the Rescue

The commands

Setup guide to prepare for passkeys in your Rails development environment

Writeup about Noko's new dialogs framework

What is `PracticalFramework`? What is `PracticalViews`?

Decouple `FormBuilders` with sidechained components

Sidechained `ViewComponents`

Example: `Form::InputComponent`

Example: `Forms::LocationFieldComponent` (Application-specific input component)

Sane icon management with an `IconSet` PORO

Forms should be components, and live in the `Forms::` namespace

Time to `mix` and `grab` from Phlex

Use `call` for basic components, `tag.*` helpers for complex attribute serializing

`puma-dev` to the Rescue