One of the lesser known code smells, Divergent Change is one of the strongest multipliers of tech debt. Fixing it has high leverage, so we’ll explore how to spot and remediate it.

What Is Divergent Change?

Divergent Change belongs to the code smells class of Change Preventers. As such, it is a major impediment for your development velocity, which is why it should be treated swiftly when you spot it.

In one sentence, you are likely dealing with this smell if one class changes often, but for unrelated reasons. Another hint is the necessity to change a class in multiple places when altering it or a dependency. It is the mirror-universe counterpart of Shotgun Surgery, in which many classes change for the same reason.

I am going to demonstrate this with an Alert ViewComponent:

class AlertComponent < ViewComponent::Base
  def initialize(state:, message:)
    @state = state
    @message = message
  end

  def color
    {
      success: "green",
      info: "blue",
      error: "red"
    }
  end
  
  def icon
    {
      success: "check",
      info: "info",
      error: "exclamation"
    }
  end
  
  def message
    prefix = case state
      when :success then "YIPPEE!"
      when :info then "Listen up:"
      when :error then "Oh Dear."
    end
      
    "#{prefix} #{@message}"
  end
end

Suppose we want to add a new type of status, warning, we now have to edit three individual methods. This example is trivial, but imagine these methods are actually spread out between several modules. Suddenly a single change turns into a bug chasing contest.

What Makes Divergent Change So Harmful?

Every “change preventer” is malign, but Divergent Change is often harder to spot than its colleagues. That’s especially the case if a class’ behavior is scattered between various modules, for example Rails’ ActiveSupport concerns.

That’s why extracting a concern solely to include it in a single class - albeit reducing perceived complexity - is itself considered a smell. It disguises that a class doesn’t follow the Single Responsibility Principle, and should be better treated with other techniques, for example composition.

Often, divergent change starts out pretty innocent: “Oh, I’ll just use a hash as a lookup table”, or “one case statement won’t hurt”. A simple enough choice in the YAGNI spirit - fair enough. The problem is one of setting an example, i.e. culture. The next developer who needs to program a feature in this class sees the pattern and does the next best thing under deadline pressure - add another conditional. Thus, gradually the class becomes a God Class with far too many concerns mixed into its responsibility - another way of circumscribing Divergent Change. What’s worse, such a static structure of conditionals and constants makes it hard to refactor and employ a behavioral design pattern like Strategy or Visitor, which allow to dynamically attach behavior at runtime.

How Do I Detect Divergent Change in My Codebase?

In contrast to Shotgun Surgery, which is easier to spot (you just have to grep a certain method or class in your codebase), Divergent Change is a master of camouflage. Chances are you already have many such offenses in your codebase which are hiding in plain sight. Let’s look at a strategy to detect it by first narrowing down the potential offenders, then looking for specific symptoms.

Conveniently, Attractor already equips you with the relevant code metrics to filter your classes in search of Divergent Change:

• Churn (how often a class has changed)
• Complexity (how hard it is to understand what the class is doing)

If you restrict your search to those files exhibiting both a high churn count and complexity, you are likely to come across a couple of God Classes that display the symptoms outlined above.

That’s of course only narrowing down the search space. We have to do a bit of detective work to tease out the offenses. Here are a few indicators that you should be familiar with:

• Looking through the version control log, you see many changes that aren’t related to each other
• If you skim through these commits, you notice that more than one class or module was modified
• The class has a lot of control flow logic (i.e. conditionals)

How Do I Treat Divergent Change?

As a general heuristic, you should strive that each class only serves one purpose. Ideally you can describe what it does in a single sentence. That, of course, is only a very general guideline.

I will start out with a simple refactoring that introduces composition by extracting a class (hierarchy). Bear with me, I’m deliberately taking this step by step.

class Alert
  def initialize(message:)
    @message = message
  end
end

class SuccessAlert < Alert
  def color = "green"
  def icon = "check"
  def message = "YIPPEE! #{@message}"
end

class InfoAlert < Alert
  def color = "blue"
  def icon = "info"
  def message = "Listen up: #{@message}"
end

class ErrorAlert < Alert
  def color = "red"
  def icon = "exclamation"
  def message = "Oh Dear. #{@message}"
end

class AlertComponent < ViewComponent::Base
  VALID_ALERTS_BY_STATE = {
    success: SuccessAlert,
    info: InfoAlert,
    error: ErrorAlert
  }

  def initialize(state:, message:)
    @state = VALID_ALERTS_BY_STATE[state].new(message: message)
  end
  
  delegate :color, :icon, :message, to: :state
end

Note how this simple refactoring has already reduced the changes that have to be made to add a new type of alert from 3 to 2: Instead of altering 3 methods, I now only have to add one class, and add it to the VALID_ALERTS_BY_STATE hash.

We can do better though. We harness Rails’ developers dearest paradigm - Convention over Configuration - to simplify the class lookup:

class AlertComponent < ViewComponent::Base
  def initialize(state:, message:)
    @state = "#{state.classify}Alert".safe_constantize.new(message: message)
  end
  
  delegate :color, :icon, :message, to: :state
end

Now we’ve also gotten rid of the lookup hash and simply assume that the class name adheres to a certain naming scheme. Note that both these approaches still require that you know which are valid states to pass into the component. As we will see in a moment, there’s a yet better way to go about this.

How Can I Prevent It?

There are two SOLID principles that should be your yardsticks here: The Open/Closed Principle, and Dependency Inversion.

Open/Closed Principle

Paraphrased a bit, it goes like this:

Software entities should be open for extension, but closed for modification.

We have seen in the above example that adding a new type of alert would have meant tinkering with the internals of AlertComponent quite a bit. You should always strive to see classes as “finished” entities and not interfere with their implementation if possible. Of course, this requires discipline and often quick iteration in the product development lifecycle exacerbates the situation.

With refactorings like the above we have already improved the situation. Still, there’s a bit of concern regarding the alert class lookup: If the naming convention was ever to change, we’ll have to touch a lot of classes, again. It would be better if the AlertComponent didn’t have to bother with that at all and were extensible by design. This is where the next principle comes in.

Dependency Inversion

In short, this principle demands that the software inverts control. Lower level modules (our Alert classes) should be passed into higher level modules (our AlertComponent) instead of the latter depending on the former. Rather, they should be treated as abstractions. What does this mean? Let’s take a look:

class AlertComponent < ViewComponent::Base
  def initialize(alert:)
    @alert = alert
  end

  delegate :color, :icon, :message, to: :alert
end

Now the AlertComponent class is completely decoupled. We have inverted control, i.e. the component simply relies upon the passed in alert to understand color, icon, and message. It would be called like this:

render AlertComponent.new(alert: SuccessAlert.new(message: "You have successfully inverted control"))

Notably, the component now isn’t concerned with adding a new type of alert at all anymore. All we’d have to do is implement it as a class and inject it:

class WarningAlert < Alert
  def color = "yellow"
  def icon = "triangle-exclamation"
  def message = "Yikes. #{@message}"
end

render AlertComponent.new(alert: WarningAlert.new(message: ""))

References

• Thoughtbot Article
• Refactoring Guru

This post originally appeared on the AppSignal blog as part of a two part series

Ruby on Rails with its strong emphasis on convention over configuration has obviated many architectural considerations that were causes of bikeshedding when building web applications.

Still, one area that has continuously piqued developers’ interest is how to handle business logic, i.e. code that epitomizes “what the app does”.

Another way to phrase this question is:

Where do we put all the transactional code?

There has been an ongoing debate about this topic in the Rails community, with two extremes being advocated for, and a couple of intermediate solutions.

On the one hand, there’s the “Golden Path” which fully embraces MVC and is most prominently followed by 37Signals. On the other hand there is Domain Driven Design (DDD) which is practiced by companies like Shopify and consultancies like Arkency.

All these alternative approaches look pretty heavy handed. Which one is for you depends very much on

• how many business domains an app spans (DDD)
• organizational structure
• app architecture/infrastructure (microservices/monolith, k8s/cloud/…)

Let’s take a closer look at some of the familiar alternatives, and their pros and cons:

Fat Models

are models that are equipped with methods for processing their data, possibly resulting in side effects and updating other records. Consider this example, simplified from Jorge Manrubia’s post about rich models:

# app/models/recording
class Recording < ApplicationRecord
  def copy_to(bucket, parent: nil)
    copies.create! destination_bucket: bucket, destination_parent: parent
  end
end

One problem with fat models is that unless you are really disciplined in your code hygiene, they can tend towards an assortment of code smells:

• Feature Envy: models reaching out to other models, either to query their internals (a “tell, don’t ask” violation) or to actually mutate them, are a red flag 🚩. To achieve low coupling, objects should be confident just sending messages to other objects without querying them for the results.
• Single Responsibility Principle Violations: models encoding interactions with other models may break the rule of single responsibility. Keep rigorously asking yourself if the code you are adding to a class is really belonging to the representation of the object it describes.
• Logic in Callbacks: An enduring controversy, model callbacks are really a two-sided sword. A powerful tool, they can simplify a lot of imperative code, but can also hide complexity and lead to bugs that are hard to track down. Here is a rule of thumb you could follow: Only use model callbacks to prepare or postprocess self, never trigger any jobs, mailers, or other services from them.
• Tendency towards God Objects: Rich models act as attractors for functionality. Wait a few development cycles and I’ll take any bet there’ll be at least one model accumulating a few dozen methods. Even splitting up such an object into model concerns is merely an act of covering up the mess 🌶️.

The points listed above can be summarized as a question of perspective: Paraphrasing Jim Gay, is a look from within an individual model actually a good vantage point to design what your app does?

This is something a more recent development in Rails development has picked up, namely

Service Objects

Really another title for the Command Pattern, service objects encapsulate a “unit of work”, or “action”, that usually involves several steps of transactional logic. Following the example from above, you would typically formulate something like this:

# app/services/recording_copier.rb
class RecordingCopier
  def call(source, destination)
    source.copies.create! destination_bucket: destination
  end
end

There are multiple problematic facets of this pattern, but their focal point is:

This object does not encapsulate any instance state.

This is a sign that they do not actually, as Jason Swett has noticed, describe any concept of our domain.

Others, like Avdi Grimm have observed that they run counter the accepted practice of representing objects of your domain with nouns, and messages sent to these objects with verbs. Classes named using the nominalization of a verb are an indicator that you identified a message you want to send but couldn’t come up with a receiver, i.e. a matching role to send it to. Such objects with fuzzy responsibilities can be the hardest to refactor.

First and foremost, though, I always found this concept a bit confusing, because Rails already has a built-in primitive for this:

Jobs

In my consulting practice I’ve observed that jobs are generally underused, because their limits and requirements can seem daunting. Let’s first rewrite our example as a job:

# app/jobs/copy_record_job.rb
class CopyRecordJob < ApplicationJob
  def perform(source, destination)
    source.copies.create! destination_bucket: destination
  end
end

As you can see, there’s almost no syntactical difference to a service object. What, then, sets them apart?

A couple of things, actually:

• the code above isn’t idempotent. If you run it twice, it will create two copies, which is probably not what you intended. Why is this important? Because most backend job processors like Sidekiq don’t make any guarantees that your jobs are run exactly once.
• jobs cannot return a value, or indicate when they are done out of the box (although you can do this manually via callbacks, for example).

There are several workarounds for this, like the magnificent Acidic Job gem, or Sidekiq Pro/Enterprise features around enhanced reliability and unique jobs. Still, if they occur, bugs related to missing jobs and/or job idempotency are hard to track down, and harder to fix.

Event Sourcing

Event Sourcing ensures that all changes to application state are stored as a sequence of events. Not just can we query these events, we can also use the event log to reconstruct past states (Martin Fowler)

Essentially, event sourcing boils down to a publish/subscribe algorithm with integrated versioning. It’s a high-level Domain Driven Design concept that I will not discuss in detail here.

That’s not to say it’s not an interesting pattern. You should use it if you have advanced reporting requirements, for example. If you want to learn more about it, take a look at https://railseventstore.org/, for example.

Enter DCI (Data, Context, Interaction)

DCI is an often overlooked paradigm that’s able to circumvent a lot of the issues outlined in the sections above, while still adhering to MVC. More importantly though, it’s a code architecture style that simultaneously lets us consider the application as a whole, while at the same time avoiding the introduction of objects with unclear responsibilities. Without further ado, here’s the definition from Wikipedia:

The paradigm separates the domain model (data) from use cases (context) and roles that objects play (interaction). DCI is complementary to model–view–controller (MVC). MVC as a pattern language is still used to separate the data and its processing from presentation.

One of the main objectives of DCI is to improve a developer’s understanding of system-level state and behavior by putting their code representation into different modules:

• slowly changing domain knowledge (what a system is)
• rapidly changing system behavior (what a system does)

Moreover, it tries to simplify the mental models of an application a developer has to deal with by grouping them into use cases.

Let’s break this down into its individual parts:

Data

In DCI terms, Data encompasses the static, descriptive parts of what in MVC we call the Model. It explicitly lacks any functionality that involves any interaction with other objects. In other words, it’s devoid of business logic.

class BankAccount
  attr_reader :balance

  def increase(by)
    @balance += by
  end

  def decrease(by)
    @balance -= by
  end
end

Consider the simple BankAccount class above: It allows querying its balance, as well as to increase or decrease it. But there is no such concept as a transfer to another account.

Wait a second, I hear you say, isn’t that the description of an anaemic model? And isn’t that the most horrific anti-pattern of all time 👻? Bear with me for a moment…

Context

The point of DCI is not to strip models of any domain logic, but to dynamically attach it when it’s needed, and tear it down afterwards. The concept of Context realizes this.

A context is responsible for identifying a use case and mapping data objects onto roles that those play therein.

The nice thing, by the way, is they align nicely with our mental models of every day processes. People don’t carry around every role with them all the time, either.

In a school classroom, for example, we’re all people, but some are teachers, and some students.

In a public transport, some are passengers, some are conductors. Some even play multiple roles at once, and they may change over time:

• I’m a passenger,
• if it’s a long ride, I might also assume the role of book reader,
• if someone calls me on the phone, I’m simultaneously a conversation participant,
• if I travel with my daughter, I’m also her Dad and have to look after her,
• and so on…

Let’s continue with the BankAccount example from above, and expand it by the requirement for transferring money from one to the other. Consider the following module, which just defines a method to transfer money from one account to the other:

module MoneyTransferring
  def transfer_money_to(destination:, amount:)
    self.decrease amount
    destination.increase amount
  end
end

The key notion in this snippet is the reference to self, as we shall see in a moment.

The beauty of applying this pattern in Ruby originates from the ability to inject modules at run time. A context would then map the roles of source and destination:

class Transfer
  delegate :transfer_money_to, to: :source

  def initialize(source:)
    @source = source
    @source.include(MoneyTransferring)
  end
end

Thus, now BankAccount is equipped with the ability to transfer_money_to another account, in the Transfer context.

Interaction

The final part of this pattern comprises everything the system does.

It is here that through triggers the use cases of the application are enacted:

Transfer.new(source: source_account)
  .transfer_money_to(destination: destination_account, amount: 1_000)

The source and destination roles are mapped to the respective domain models, and the transfer takes place. In a typical Rails app, this would happen in a controller, or a job - in some cases even in model callbacks.

A critical constraint of DCI is that these bindings are guaranteed to be in place only at run time. In other words, the Transfer object will be picked up by the garbage collector afterwards, and no trace of the mapped roles remains with the domain models.

If you flip this around, you’ll notice that this ensures that DCI roles are generic, which makes them both easier to reason about and test. In other words, the Transfer context makes no assumptions about the kind of objects its roles are being mapped to, it only expects increase/decrease methods. The fact that they are BankAccounts with attached state is irrelevant! They could equally be other types of objects (Wallets, StockPortfolios, MoneyBox, …), the context does not care. It is only through its enactment in a certain use case that the roles are associated with certain types, and as the snippet above shows, it’s succinct and readable.

Case Study

I want to conclude this article with an example from a real-world app where I use DCI to organize parts of the business logic. I will attempt to show how regular Rails MVC can be used to enact a DCI use case. Note that I’m using Jim Gay’s surrounded gem to strip away some of the boilerplate.

Here’s a Checkout context that includes methods to create and fulfill a Stripe::Checkout:Session object:

# app/contexts/checkout.rb
class Checkout
  # ...   

  role :payable do
    def create_session
      Stripe::Checkout::Session.create({
        line_items: line_items, # provided by model
        metadata: {
          gid: to_gid.to_s
        },
        success_url: polymorphic_url(self) 
        # ...
      })
    end
    
    def fulfill
      # ...
    end
  end
end

Imagine that the class method role :payable is just a wrapper around the manual .include(SomeModule) we did above; create_session and fulfill are called the RoleMethods of this context. Note that in this case, the create_session method only relies on self, to_gid (which is present on any ActiveRecord::Base subclass), and a line_items accessor.

We can now write a test for the enactment of this context:

class CheckoutTest < ActiveSupport::TestCase
  # VCR/Stub setup omitted

  test "created stripe checkout session includes gid in metadata" do
    @quote = quotes(:accepted_quote)
    
    session = Checkout.new(payable: @quote).create_session
    
    assert_equal @quote, GlobalID::Locator.locate(session.metadata.gid)
  end
end

This looks good, now let’s take a look at two separate use cases for this context:

Use Case 1: Quote Checkout

In my app, a Quote is a bespoke offer to a certain customer. It typically contains only one line item, which will be used by Stripe to create a price:

# model
class Quote
  def line_items
    [{price: price_id, quantity: 1}] # Stripe::Price
  end
end

In a controller, now a Stripe Checkout session can be created as follows:

# controller
@checkout_session = Checkout.new(payable: @quote).checkout_session 

This is then used in the view to send the customer to a Stripe Checkout form via a simple link:

<!-- view -->
<%= link_to @checkout_session.url, target: "_top", class: "btn btn-primary", id: dom_id(@quote, :checkout_button) do %>
  <%= t(".checkout") %>
<% end %>

Use Case 2: Review Checkout

Another payable in my app is called a Review, which contains many chapters, each of them their own line item:

# model
class Review
  def line_items
    chapters.map do |chapter|
      {price: chapter.price_id, quantity: 1} # Stripe::Price
    end
  end
end

Apart from exchanging the payable, the code for enacting the checkout use case stays exactly the same:

# controller
@checkout_session = Checkout.new(payable: @review).create_session 

<!-- view -->
<%= link_to @checkout_session.url, target: "_top", class: "btn btn-primary", id: dom_id(@review, :checkout_button) do %>
  <%= t(".checkout") %>
<% end %>

Takeaways

DCI certainly isn’t a grab-all solution to code organization, but compared to some of the other approaches it feels like a natural inhabitant of a Rails app’s ecosystem. What enthralls me the most is that it provides a clear structure for separating descriptive structure (“what the app is”) from behavior (“what the app does”) without compromising the SOLID principles for OOP design. This separation makes it a breeze to refactor key parts of such an app.

Actual design of business logic also feels more streamlined, because DCI attempts to reflect the mental models we construct of the software we build more closely.

That said, like any design pattern or paradigm out there, it’s not a hammer that fits every nail. You might find that this separation of behavior from data is something that diminishes code cohesion in your app, for example.

If you would like to try it on for size, I would recommend using it for integrating third party APIs, or with fringe concerns that don’t directly touch your app’s core functionality. That’s because those are areas that typically don’t change very often and are thus ideal playgrounds for experimenting with new tools.

References

• Clean Ruby eBook
• Surrounded Gem

This post is proudly sponsored by Code & Co.

Disclaimer: I’m not affiliated to fly.io at all, this is just a personal account of my experience with it.

Fly.io 101

Even though fly is pretty much “Phoenix First” these days (they hired Chris McCord for a reason!), it’s still a very decent way to deploy a Reactive Rails app, as Matt Yorkley has demonstrated here. Let’s go through a quick list of preliminary information before we get started.

Docker or Buildpacks?

A lot of Rails developers considering Fly as a Platform as a Service these days are accustomed to the Heroku way of deploying apps via git push and Cloud Native Buildpacks that manage the deployment process automatically. While Fly defaults to a Dockerfile builder - and indeed, the Rails setup wizard will generate one for you, as we shall see - you can also use a buildpack builder by specifying a builder and buildpacks in the fly.toml configuration:

[build]
  builder = "heroku/buildpacks:18"
  buildpacks = ["...", "..."]

Also refer to this blog post to select the correct builder (at the moment of writing this would be heroku/buildpacks:18)

Free Allowances

While Fly has a quite generous stack of free allowances which will let you start and maintain a reasonably sized side-project for free, I would like to specifically point out their free postgres offering, which largely builds on the allowed 3GB of volume storage. Here are a few examples for how to configure it. Bear in mind though that the free compute allowance is summed together for all apps - if you exceed that, you might not be able to keep your whole Rails project free.

Getting Started

1. The first thing you’ll want to do, is to install the flyctl CLI (see here)
2. Next, quite obviously, you need to create a Fly account. Run flyctl auth signup, which will in turn open the browser for you. Note that you will have to provide credit card information upfront, because ”here’s what happens if you give people freemium full access to a hosting platform: lots and lots of free VMs mining for cryptocurrencies.” Fair enough from my vantage point.
3. Run flyctl auth login to authenticate against Fly.

Now you’re all set up to deploy your first app.

Setup Wizard

For the remainder of this walkthrough, let’s assume you have a simple Rails app called my-app, and your terminal’s working directory is pointing to the root folder of this app.

I’ll start this by a rundown of the official Rails Getting Started tutorial, before I dive into a little more advanced topics.

The setup wizard for Rails apps is suprisingly helpful. If you run fly launch it will:

1. Detect a Rails app
2. Ask you to specify your organization and primary region
3. Produce a fly.toml file, which we will look at later
4. Ask whether you would like to set up a Postgresql database right now. If you do that, it will save you the effort of creating and attaching to it manually. This is eminently helpful because it sets up the DATABASE_URL via an application secret right away.
5. It then rattles through the process of preparing your app for deployment. Notice that it is not yet deployed at this stage!

Below is a sample output of that command:

$ fly launch
Creating app in /.....
Scanning source code
Detected a Rails app
? App Name (leave blank to use an auto-generated name): my-app

? Select organization:  Julian Rubisch (personal)
? Select region:  fra

Created app my-app in organization personal
Wrote config file fly.toml
? Would you like to setup a Postgresql database now? y

? Select configuration:  [Use arrows to move, type to filter]
> Development - Single node, 1x shared CPU, 256MB RAM, 1GB disk
  Production - Highly available, 1x shared CPU, 256MB RAM, 10GB disk
  Production - Highly available, 1x Dedicated CPU, 2GB RAM, 50GB disk
  Production - Highly available, 2x Dedicated CPUs, 4GB RAM, 100GB disk

Creating postgres cluster my-app-db in organization personal
[...]

Postgres cluster my-app-db is now attached to my-app
The following secret was added to my-app:
  DATABASE_URL=postgres://xxxxxxx:xxxxxxx@top2.nearest.of.my-app-db.internal:5432/my-app
Postgres cluster my-app-db is now attached to my-app

Your Rails app is prepared for deployment. Production will be setup with these versions of core runtime packages:

Ruby 3.0.0
Bundler 2.2.5
NodeJS 14
Postgres cluster my-app-db is now attached to my-app
The following secret was added to my-app:
  DATABASE_URL=postgres://xxxxxxx:xxxxxxx@top2.nearest.of.my-app-db.internal:5432/my-app
Postgres cluster my-app-db is now attached to my-app

Your Rails app is prepared for deployment. Production will be setup with these versions of core runtime packages:

Ruby 3.0.0
Bundler 2.2.5
NodeJS 14

[...]

run 'fly deploy --remote-only' 

The fly.toml configuration file created for you by the CLI looks like this:

# fly.toml file generated for my-app on 2022-06-06T13:44:47+02:00

app = "my-app"

kill_signal = "SIGINT"
kill_timeout = 5
processes = []

[build]

  [build.args]
    BUNDLER_VERSION = "2.2.5"
    NODE_VERSION = "14"
    RUBY_VERSION = "3.0.0"

[deploy]
  release_command = "bundle exec rails db:migrate"

[env]
  PORT = "8080"
  SERVER_COMMAND = "bundle exec puma -C config/puma.rb"

[experimental]
  allowed_public_ports = []
  auto_rollback = true

[[services]]
  http_checks = []
  internal_port = 8080
  processes = ["app"]
  protocol = "tcp"
  script_checks = []

  [services.concurrency]
    hard_limit = 25
    soft_limit = 20
    type = "connections"

  [[services.ports]]
    force_https = true
    handlers = ["http"]
    port = 80

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

  [[services.tcp_checks]]
    grace_period = "1s"
    interval = "15s"
    restart_limit = 0
    timeout = "2s"

[[statics]]
  guest_path = "/app/public"
  url_prefix = "/"

Observe that it has

• acquired BUNDLER_VERSION, NODE_VERSION and RUBY_VERSION from your app
• set the SERVER_COMMAND to a puma startup command
• added a release_command that will run your migrations, as you are probably used to if you are a Heroku user.

Furthermore, a Dockerfile should have been created for your perusal, or, more specifically, for Fly to use for deployment. I won’t reproduce a listing of this file here (you can easily take a look at it yourself if you follow the steps above), but point out some interesting details:

1. It uses a Fullstaq Ruby image with jemalloc enabled. You can read in its FAQ why that is a good thing to have turned on by default
2. It uses volta.sh to install node and yarn
3. It then uses multi-stage Docker builds to install OS packages, gems, and node packages separately
4. Finally, it will copy your app directory and run rails assets:precompile for you.

A short aside: At this point, I usually like to create a fly directory which will hold all the configuration files for Fly (because there will be more!):

$ mkdir fly
$ mv fly.toml fly

Deploy

Now we’re ready to deploy our app! Let’s pause for a moment, though, and import the RAILS_MASTER_KEY to the Fly app’s secrets (assuming you’re on Rails >= 6.1):

$ fly secrets set RAILS_MASTER_KEY=$(cat config/master.key) -c fly/fly.toml

The deploy itself is then only a matter of running

$ fly deploy --remote-only -c fly/fly.toml

Note: the --remote-only option tells Fly to use a remote builder (which are free) other than your local Docker installation - which especially useful if you, like me, are working on an Apple Silicon/ARM64 based computer which might lead to issues.

Assuming this command completed without errors, you should be able to inspect your app in the Fly dashboard:

Along with the accompanying, separate database app:

Redis

Chances are, since we are talking about reactive Rails applications, you will need a key/value store like Redis for ActionCable, Sidekiq, Fragment Caching, and other usual suspects.

Now, even though there is a blog post about how to achieve globally distributed Redis by the fly founder, Kurt Mackey, I’d like you to hold your breath for a second. There is another option that fits our bill even better: KeyDB, which was recently acquired by Snap.

From the project’s README:

KeyDB is a high performance fork of Redis with a focus on multithreading, memory efficiency, and high throughput.

Quite precognitive, the Fly crew has put together a KeyDB sample app for our usage at https://github.com/fly-apps/keydb/. One of the taglines is:

KeyDB also supports a multimaster mode which is uniquely suited to deployment on Fly.

Beware though that this doesn’t enforce strong consistency, which isn’t an issue for most use cases, but you might consider using traditional Redis for your ActiveJob processor (we’ll come back to that later).

KeyDB Walkthrough

The process starts with cloning said Github repository to your app. I always do this in a fly/keydb folder, as a git submodule, like so:

$ mkdir fly/keydb-cache
$ git clone https://github.com/fly-apps/keydb.git fly/keydb-cache
$ cd fly/keydb-cache

Before you proceed, crack open fly/keydb-cache/fly.toml in your editor and rename it to reflect your main app’s name. Note that I also labelled it “cache” to discern it from future additional instances.

app = "my-app-keydb-cache"

[mount]
  destination = "/data"
  source = "keydb_server"

$ fly launch

An existing fly.toml file was found for app keydb-multimaster-example
? Would you like to copy its configuration to the new app? Yes
Creating app in /Users/jrubisch/.../my-app/fly/keydb-cache
Scanning source code
Detected a Dockerfile app
? App Name (leave blank to use an auto-generated name): my-app-keydb
? Select organization: Julian Rubisch (personal)
? Select region: fra (Frankfurt, Germany)
Created app my-app-keydb in organization personal
Wrote config file fly.toml
? Would you like to setup a Postgresql database now? No
? Would you like to deploy now? No
Your app is ready. Deploy with `flyctl deploy`

This sets up our app for deployment, but we pause here for a second to prepare a few things, namely authentication of our KeyDB app, and persistent storage.

The standard configuration requires us to set a KEYDB_PASSWORD; afterwards we create a volume called keydb_server (as was referred to in the above config file) in every region we’d like to deploy and synchronize this KeyDB app. Note that I’ve restricted the size to 1GB in this example, since that is enough for a side project or staging configuration - you might want to increase this according to your app’s requirements. Finally, we deploy.

$ fly secrets set KEYDB_PASSWORD=password

$ fly volumes create keydb_server --size 1 --region fra
$ fly volumes create keydb_server --size 1 --region ... # repeat for every region

$ fly deploy

Here’s an important takeaway: By default, fly uses volumes to control region placement, so an app will be spun up for every region where you deployed a volume. You’ll later want to deploy an instance of your main app to every region with a KeyDB instance, but we’ll cover that later.

Advanced KeyDB Config

If your app runs for a while, chances are your KeyDB instance will fill up with data. Luckily for us, KeyDB supports standard Redis configuration options (refer here for a full listing). From those, maxmemory and maxmemory-policy are the most important ones, which I’ve appended to the default config (to be found at fly/keydb-cache/keydb.conf).

dir /data/ 
protected-mode no 
appendonly no

# snapshotting
save 900 1
save 300 10
save 60 10000

# replication
active-replica yes
multi-master yes
replica-serve-stale-data no

# add these:
maxmemory 100mb                # scale at your own leisure
maxmemory-policy allkeys-lru   # or try allkeys-lfu

Note that LRU stands for “Least Recently Used” while LFU means “Least Frequently Used”. When you’ve added your configuration options, just deploy again. If you’d like to take a look at a KeyDB-with-Rails app example, here’s one using AnyCable: https://github.com/superfly/anycable-rails.

Multiple Instances

Depending on your app’s architecture and size, you may want to deploy more than one KeyDB instance (e.g. one for ActionCable, one for the Rails cache, one for kredis, maybe even one for session storage, etc.) To achieve that, start over and clone a new version of the original KeyDB repo, to, for example, fly/keydb-cable etc. Below we’ll talk about how to adapt your configurations accordingly.

Regionalized App Configurations

Finally, Fly.io’s USP are globally distributed operations, and we want to capitalize on that, of course. Luckily, Fly’s VM configuration makes it easy for us to do exactly that.

Fly’s internal private networking uses region qualifiers that are exposed to your app as the FLY_REGION environment variable. Thus we can refer to the KeyDB instance(s) pertaining to the region where our Rails app is deployed like so:

• config/cable.yml

# ...
production:
  adapter: redis
  url: <%= "redis://#{ENV['FLY_REGION']}.#{ENV['REDIS_CABLE_HOST']}/1" %>
  password: <%= ENV.fetch("REDIS_CABLE_PASSWORD", "password") %>
  channel_prefix: my_app_production

• Cache configuration, in your environment config file (e.g. config/production.rb)

# ...

config.cache_store = :redis_cache_store, {
  url: "redis://#{ENV["FLY_REGION"]}.#{ENV["REDIS_CACHE_HOST"]}/1",
  password: ENV["REDIS_CACHE_PASSWORD"]
}

# ...

• Kredis configuration, config/redis/shared.yml

# ...

production: &production
  url: <%= "redis://#{ENV['FLY_REGION']}.#{ENV['REDIS_KREDIS_HOST']}/0" %>
  password: <%= ENV["REDIS_KREDIS_PASSWORD"] %>
  timeout: 1

etc.

Note that I used different HOST and PASSWORD environment variables for each KeyDB instance. Before we can deploy our main Rails app again, we must set them as Fly secrets:

In your app’s root directory do:

$ fly secrets set REDIS_CABLE_PASSWORD=password -c fly/fly.toml
$ fly secrets set REDIS_CABLE_HOST=my-app-keydb-cable.internal:6379 -c fly/fly.toml    

$ fly secrets set REDIS_CACHE_PASSWORD=password -c fly/fly.toml
$ fly secrets set REDIS_CACHE_HOST=my-app-keydb-cache.internal:6379 -c fly/fly.toml    

$ fly secrets set REDIS_KREDIS_PASSWORD=password -c fly/fly.toml
$ fly secrets set REDIS_KREDIS_HOST=my-app-keydb-kredis.internal:6379 -c fly/fly.toml    

After that, we are ready to fly deploy -c fly/fly.toml again.

Background Workers

Before we start our exploration of how to set up worker nodes for job processors like ActiveJob, Sidekiq etc., we need to consider a preliminary question:

Do we want to run both app server (i.e. puma) and worker processes inside the same app/instance or in separate ones?

In other words, do we favor the Heroku approach (one “dyno” per workload), or do we want to leverage Fly’s multi-process support? There’s pros and cons to each approach, let’s quickly consider them:

You will have to make the decision for yourself, but the more flexible one, in my opinion is to run them as separate Fly apps. Additionally, multi-processes are still currently a preview feature as detailed out in this blog post. We are going to run with the multi-app option for the moment, so let’s just clone our fly.toml to a separate fly.worker.toml:

$ cp fly/fly.toml fly/fly.worker.toml
$ fly launch --name my-app-worker --no-deploy
Creating app in /Users/jrubisch/Documents/_CODE/saas/my-app
Scanning source code
Detected a Dockerfile app
Selected App Name: my-app-worker
? Select organization: Julian Rubisch (personal)
? Select region: fra (Frankfurt, Germany)
Created app my-app-worker in organization personal
Wrote config file fly.toml
? Would you like to setup a Postgresql database now? No
? Would you like to deploy now? No
Your app is ready. Deploy with `flyctl deploy`

Be careful though to remove the migration release command to avoid race conditions. Also, change the SERVER_COMMAND to your job processor (Sidekiq in the example blow) accordingly, and delete any services (since a worker node shouldn’t expose any port to the public).

app = "my-app-worker"

kill_signal = "SIGINT"
kill_timeout = 5
processes = []

[build]

  [build.args]
    BUNDLER_VERSION = "2.2.5"
    NODE_VERSION = "14"
    RUBY_VERSION = "3.0.0"

# remove this 👇🏻
# [deploy]
#   release_command = "bundle exec rails db:migrate"

[env]
  # change this 👇🏻
  SERVER_COMMAND = "bundle exec sidekiq -C config/sidekiq.yml"

[experimental]
  allowed_public_ports = []
  auto_rollback = true

# a worker node doesn't expose any services
# [[services]]
# deleted 🚮

Worker Redis

I mentioned above that there’s some nuance to how to deal with Redis in the context of workers. While for a side project you might be fine with deploying another (or the same) KeyDB instance, for production scenarios you’ll want to err on the safe side and use a vanilla Redis instance with all the consistency guarantees that multi-master KeyDB does not offer. Also, chances are you don’t actually want to send data for your workers around the globe, so a single Redis instance per region, holding the ActiveJob/Sidekiq serialization data is not only good enough, but probably exactly what we are looking for.

For this, I usually just fall back to the Redis on Fly reference, i.e. create a fly app using fly launch and configure as you go, or just create a separate config file at fly/fly.redis.toml:

app = "my-app-worker-redis"

kill_signal = "SIGINT"
kill_timeout = 5
processes = []

[build]
  image = "flyio/redis:6.2.6"

[env]
  MAXMEMORY_POLICY = "noeviction"

[experimental]
  allowed_public_ports = []
  auto_rollback = true

[metrics]
  port = 9091
  path = "/metrics"

[[mounts]]
  destination = "/data"
  source = "redis_server"

Note that MAXMEMORY_POLICY can be set as an environment variable as per the docs. In the case of your job processor backend, you want this to be noeviction, because you decidedly want it to fail loudly before any jobs are silently dropped.

We then go through the fly launch, fly deploy cycle again:

$ fly launch --name my-app-worker-redis --no-deploy
$ fly secrets set REDIS_WORKER_PASSWORD=super-secret-password -c fly/fly.redis.toml
$ fly volumes create redis_server --size 1 --region fra

Using the example of Sidekiq, you need to specify both the Redis URL and password in the same manner as we did above, for both client and server:

if Rails.env.production?
  Sidekiq.configure_server do |config|
    config.redis = {
      url: "redis://#{ENV['FLY_REGION']}.#{ENV['REDIS_WORKER_HOST']}/1",
      password: ENV["REDIS_WORKER_PASSWORD"]
    }
  end

  Sidekiq.configure_client do |config|
    config.redis = {
      url: "redis://#{ENV['FLY_REGION']}.#{ENV['REDIS_WORKER_HOST']}/1",
      password: ENV["REDIS_WORKER_PASSWORD"]
    }
  end
end

We must set those environment variables both in our app and worker images to enable communication between them:

$ fly secrets set REDIS_WORKER_PASSWORD=password -c fly/fly.toml
$ fly secrets set REDIS_WORKER_HOST=my-app-worker-redis.internal:6379 -c fly/fly.toml    

$ fly secrets set REDIS_WORKER_PASSWORD=password -c fly/fly.worker.toml
$ fly secrets set REDIS_WORKER_HOST=my-app-worker-redis.internal:6379 -c fly/fly.worker.toml    

Finally, do not forget to add your master key to the worker’s secrets. Then we are ready to deploy:

$ fly secrets set RAILS_MASTER_KEY=$(cat config/master.key) -c fly/fly.worker.toml
$ fly deploy -c fly/fly.worker.toml --remote-only

Remember to deploy both Redis and worker apps in all regions that are relevant for you!

Environments

Chances are, when you are working on any non-trivial app, you want (at least) separate staging and production environments. Well, this is the point where I must admit that there’s no Heroku CI pipelines equivalent at Fly (and the way I understand their product, this also seems vastly out of scope).

The way I usually go about this is to just duplicate the relevant configuration files in the fly directory. Building on the example app above, I’ll end up with

$ ls -l fly
-rwxr-xr-x   1  entrypoint.sh
-rw-r--r--   1  fly.redis.production.toml
-rw-r--r--   1  fly.redis.staging.toml
-rw-r--r--   1  fly.web.production.toml
-rw-r--r--   1  fly.web.staging.toml
-rw-r--r--   1  fly.worker.production.toml
-rw-r--r--   1  fly.worker.staging.toml
drwxr-xr-x  12  keydb-staging-cable
drwxr-xr-x  12  keydb-production-cable
drwxr-xr-x  12  keydb-staging-cache
drwxr-xr-x  12  keydb-production-cache
drwxr-xr-x  12  keydb-staging-kredis
drwxr-xr-x  12  keydb-production-kredis

There are probably some nifty ways to compose TOML files (alike, for example, YAML) to decrease the duplication here, but frankly I haven’t looked those up yet. I might follow this up with more information whenever I’ve got the leisure to do so and/or it hurts bad enough 😜.

Deploy Pipeline with Github Actions

The last piece in the puzzle is how to get this workflow up and running with actual CI/CD. There is actually a pretty good write-up here, but I’ll quickly walk you through the according YAML configuration file (at .github/workflows/release.yml) nonetheless.

For simplicity, I’ve combined both actions for releasing staging and production builds in one file. I employ a simple switch using if: ${{ github.ref_name == 'staging' }} to filter which steps to use, but note that you could also just put them into two separate workflow YAML files.

The only preparative step you have to take is to add the FLY_API_TOKEN (obtained with fly auth token) to your Github repository’s secrets. We then employ the official flyctl Github action to run the deploy scripts like we did from the command line - and that’s it!

name: Release

on:
  push:
    branches:
      - staging
      - master

env:
  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

jobs:
  deploy:
    name: Deploy app
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: superfly/flyctl-actions@1.3
        if: ${{ github.ref_name == 'staging' }}
        with:
          args: "deploy -c fly/fly.worker.staging.toml"
      - uses: superfly/flyctl-actions@1.3
        if: ${{ github.ref_name == 'staging' }}
        with:
          args: "deploy -c fly/fly.web.staging.toml"
      # cheap staging/production switch
      - uses: superfly/flyctl-actions@1.3
        if: ${{ github.ref_name == 'master' }}
        with:
          args: "deploy -c fly/fly.worker.production.toml"
      - uses: superfly/flyctl-actions@1.3
        if: ${{ github.ref_name == 'master' }}
        with:
          args: "deploy -c fly/fly.web.production.toml"

Limitations

While Fly’s postgres implementation offers a lot of ops convenience out of the box (for example High Availability, easy upgrades), it’s not a fully managed solution like Heroku’s offering. Most painfully, it misses an automated backup and restore solution.

In what seemed a bit of a peculiar move, Fly’s CEO recommended CrunchyData as a cloud-native managed solution, which, at least in my understanding, defeats the advantage of having a database close to your app server by adding inter-cloud-provider latency 🤷 (addendum: even though it doesn’t seem to add that much). Even more so, as Fly was always very proud and vocal about running everything on their own hardware, but Kurt Mackey has also made it clear that Fly won’t ship postgres-specific infrastructure, and they’d rather hand off that responsibility to a third party like Supabase (by the way, let’s hope PlanetScale gets a Postgres version soon!)

To close this section on a positive note, in response to the CrunchyData recommendation, SavvyCal founder Derrick Reimer found it sufficient for his purposes, and that’s certainly quite the testimonial.

Conclusion and Follow-Up

Especially when compared with Heroku, we still had to do a lot of manual tinkering, which might seem disappointing from the distance. I see the combination of a powerful CLI with expressive configuration files as a plus, because it surfaces critical infrastructure information instead of hiding them behind a PaaS dashboard or not-easily-memorizable CLI calls. Also, having come a long way in terms of (Dev)Ops, this setup for me seems to be the sweet spot between all-too-obfuscated infrastructure abstractions that leak as soon as something out of the ordinary occurs, and completely bespoke Kubernetes deployments. But please take that last sentence with a grain of salt - your mileage may greatly vary!

What’s more, the fly CLI as well as the web app have vastly improved their functionality and UX over the last couple of months, so I’m excited where this journey takes us. Who knows, the “one click installer” of the setup concocted in this article might be just a few PRs away! Maybe it’s also just a matter of someone providing the appropriate RailsByte.

Closing this article, I’d like to make two final observations:

• Depending on your app’s requirements, it might be worth noting that multi-region postgres is a first class citizen on Fly - meaning that you can have up to date read replicas close to your app servers. Bear in mind though that writes over long-lived connections (i.e. websockets) are not recommended to work with this paradigm - in other words, package up your destructive actions in POST requests/regular form submits.
• In May 2022, litestream was announced to join Fly. In case you haven’t heard of it, here’s the elevator pitch: SQLite instances replicated via S3 (or compatible object storage) and synchronized directly to your app server (soon). From the linked article:

SQLite isn’t just on the same machine as your application, but actually built into your application process. When you put your data right next to your application, you can see per-query latency drop to 10-20 microseconds.

Wow! The future looks amazing.

This short post is intended as a how-to get up and running with StimulusReflex and the new ~importmap-rails~ gem to go all transpiler/bundler-less in your asset handling. Since not all generators in StimulusReflex have been updated to reflect this, I will keep this post updated ✌.

For reference, here is the link to the Github repository with the source code created in this walkthrough.

If you have any questions meanwhile, don’t hesitate to jump on the Discord server 💚.

Prepare Rails

Since Rails 7.0, importmaps, along with Hotwire aka Turbo and Stimulus, is the default frontend stack. Before starting out, we’ll make sure that we’re running the correct Rails version.

$ rails -v
Rails 7.0.0

$ rails new stimulus_reflex_importmaps
$ cd stimulus_reflex_importmaps

This will install and configure turbo-rails, stimulus-rails, and importmap-rails, which are the default starting with Rails 7.

Note: If you start from an existing app (e.g. Rails 6.1), you will need to add and install those yourself:

$ bundle add importmap-rails turbo-rails stimulus-rails
$ bin/rails importmap:install
$ bin/rails turbo:install
$ bin/rails stimulus:install

Set up StimulusReflex

Next, we’re going to add the StimulusReflex gem with using the most recent prerelease.

$ bundle add stimulus_reflex -v 3.5.0.pre8

Since the StimulusReflex installer hasn’t been updated to reflect the latest changes in Rails, we’ll have to do a couple of chores ourselves.

1. Enable Caching

StimulusReflex advises to use the cache store for session persistence, so we’ll configure that in development.rb:

# config/environments/development.rb
Rails.application.configure do
  # ...
  config.session_store :cache_store
  # ...
end

And enable it:

$ bin/rails dev:cache

2. Appease the StimulusReflex Sanity Checker

By default, StimulusReflex’s sanity checker will prevent your Rails process from starting if the Ruby and Javascript versions are not congruent. While the behavior of the checker is reworked at the moment, we will have to work around it for now.

To this end, set up a StimulusReflex initializer to bypass it:

$ bin/rails generate stimulus_reflex:initializer

# config/initializers/stimulus_reflex.rb

StimulusReflex.configure do |config|
  config.on_failed_sanity_checks = :warn
end

3. Pin the Required Packages

For the importmap approach, we need to use the bin/importmap tool to pin the StimulusReflex javascript package as follows:

$ bin/importmap pin stimulus_reflex@3.5.0-pre8

Pinning "stimulus_reflex" to https://ga.jspm.io/npm:stimulus_reflex@3.5.0-pre8/javascript/stimulus_reflex.js
Pinning "@hotwired/stimulus" to https://ga.jspm.io/npm:@hotwired/stimulus@3.0.1/dist/stimulus.js
Pinning "@rails/actioncable" to https://ga.jspm.io/npm:@rails/actioncable@7.0.0/app/assets/javascripts/actioncable.esm.js
Pinning "cable_ready" to https://ga.jspm.io/npm:cable_ready@5.0.0-pre8/javascript/index.js
Pinning "morphdom" to https://ga.jspm.io/npm:morphdom@2.6.1/dist/morphdom.js
Pinning "stimulus" to https://ga.jspm.io/npm:stimulus@3.0.1/dist/stimulus.js

Note that due to the namespace change that Hotwire has undergone, we have now pinned two separate Stimulus packages (@hotwired/stimulus and stimulus). StimulusReflex still references the legacy glue package stimulus, the work to transfer everything cleanly to @hotwired/stimulus is still in progress. Since we hand off the application to StimulusReflex, it shouldn’t be a problem though (see below).

4. Initialize the StimulusReflex Client

We use the ActionCable consumer obtained from Turbo’s cable interface to intialize StimulusReflex with a top level await:

// app/javascript/controllers/index.js

import StimulusReflex from "stimulus_reflex"; // <-- add this
import { application } from "./application";
import { cable } from "@hotwired/turbo-rails"; // <-- add this

// Eager load all controllers defined in the import map under controllers/**/*_controller
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading";
eagerLoadControllersFrom("controllers", application);

// Lazy load controllers as they appear in the DOM (remember not to preload controllers in import map!)
// import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
// lazyLoadControllersFrom("controllers", application)

// initialize StimulusReflex w/top-level await
const consumer = await cable.getConsumer()
StimulusReflex.initialize(application, { consumer, debug: true });

Test Everything with a CounterReflex

For the rest of this walkthrough, I follow the official Quickstart Guide closely (for any in-depth explanation of what is going on here, please look there). Let’s first add a PagesController with only an index route:

$ bin/rails g controller Pages index

# config/routes.rb

Rails.application.routes.draw do
  resources :pages, only: :index
end

# app/controllers/pages_controller.rb

class PagesController < ApplicationController
  def index
  end
end

Then, we’ll generate a CounterReflex with an increment action and use it to increase a @count index variable derived from a data-count attribute on the invoking element:

$ bin/rails g stimulus_reflex Counter increment

# app/reflexes/counter_reflex.rb

class CounterReflex < ApplicationReflex
  def increment
    @count = element.dataset[:count].to_i + element.dataset[:step].to_i
  end
end

In the index view, we’ll furnish a simple <a> tag with a data-reflex attribute that invokes this increment action on click:

<!-- app/views/pages/index.html.erb -->
<a href="#"
   data-reflex="click->Counter#increment"
   data-step="1"
   data-count="<%= @count.to_i %>">
  Increment <%= @count.to_i %>
</a>

Now it’s time to start Rails and kick the tires:

$ bin/rails s

Success! 🎉

Testing Client-Side Invocation

Now that we’ve established that the declarative way works, let’s double check that imperative client-side invocation functions, too. Again, nothing new here, refer to the relevant section in the Quick Start Guide.

Instead of a data-reflex, we are going to reference the Stimulus controller directly, and hook up a data-action:

<!-- app/views/pages/index.html.erb -->
<a href="#"
   data-controller="counter"
   data-action="click->counter#increment">
  Increment <%= @count %>
</a>

Remember that this is now dependent on our Stimulus counter_controller, so we have some work to do there:

// app/javascript/controllers/counter_controller.js

import ApplicationController from './application_controller'

export default class extends ApplicationController {
  connect () {
    super.connect()
  }

  increment() {
    this.stimulate('Counter#increment', 1)
  }
}

To stay in sync with the Quick Start guide, let’s switch to session storage and passing the step via an argument:

# app/reflexes/counter_reflex.rb

class CounterReflex < ApplicationReflex
  def increment(step = 1)
    session[:count] = session[:count].to_i + step
  end
end

We pick this up in the controller again, to render a new @count:

# app/controllers/pages_controller.rb

class PagesController < ApplicationController
  def index
    @count = session[:count].to_i
  end
end

Voilà 🥂

Conclusion

We’ve established a way to get StimulusReflex up and running with importmaps. The tooling isn’t there yet, but this post essentially lays out the steps that have to be taken to patch it. I will keep updating it as the installers and generators evolve to become importmap-rails compliant.