DEV Community: Leonid Svyatov

Ruby shipped the fix for SleeperGem 45 days before it happened

Leonid Svyatov — Tue, 21 Jul 2026 17:27:49 +0000

On June 3rd, Bundler 4.0.13 shipped a feature called cooldown. The release post described the problem it solves like this: "an account is compromised, a malicious version ships, and any bundle install in the minutes that follow resolves straight to it."

Forty-five days later, someone did exactly that to three gems.

Aikido Security disclosed the campaign on July 19th and named it SleeperGem: malicious versions of git_credential_manager, Dendreo, and fastlane-plugin-run_tests_firebase_testlab. Two of those gems had sat untouched since 2019 and 2020, which is where the name comes from. (The third impersonates Microsoft's Git Credential Manager, and no report says whether that account was hijacked or simply the attacker's.)

The clever part is what the payload does when it lands. Aikido found a skip_install? check that "scans for roughly 30 environment variables belonging to CI platforms, GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins, Vercel, and does nothing if it spots one." It sits still in your pipeline and wakes up on your laptop. StepSecurity reversed the native binary it drops: a daemon in ~/.local/share/gcm/, a systemd user unit, a cron entry, and if you installed as root, a setuid shell at /usr/local/sbin/ping6.

Most of the coverage stopped at "supply chain attack, be careful out there," then repeated numbers that do not survive a look at the registry.

The numbers being repeated are not the numbers

The most-syndicated writeup lists Dendreo versions 1.1.3 and 1.1.4 as "Published on October 14, 2017." The registry says 2017-10-14 is version 1.0.1's date, and that 1.1.2 shipped in October 2020. A 1.1.3 published three years before 1.1.2 is not a date, it is a copy-paste of the gem's first release. Same error on the fastlane plugin, where "February 06, 2018" belongs to 0.1.0. Both malicious releases went up in July 2026. That is the article the aggregators spent the next day copying.

The scale number has the same shape. Aikido's "574,661 total downloads" is honest in context (it says all versions), but downstream it sits next to the attack and reads like blast radius. Here is where they live:

`fastlane-plugin-run_tests_firebase_testlab`	published	downloads
0.3.1	2019-03-04	531,859	`################################`
0.2.0	2018-07-17	16,509	`#`
0.1.0	2018-02-06	10,619	`#`
0.2.2	2018-11-29	6,323
0.3.0	2019-01-11	4,965
0.2.1	2018-09-27	4,892
0.3.2	2026-07-19	yanked, count deleted

One benign release from 2019 is 92.5% of it. Dendreo has 14,435 downloads across its entire seven-year life. Nobody publishes install counts for the malicious versions, and they can't: yanking a version removes it from the API.

The mitigation was already on the shelf

Cooldown makes Bundler refuse to resolve to a release younger than N days. The first malicious version went up on July 18th, and all of them were gone from the registry by the 21st. Nobody published the actual yank time, so three days is an upper bound, not a measurement, but a cooldown of seven would have skipped every one of them for as long as they existed.

It is one line:

source "https://rubygems.org", cooldown: 7

I checked it against a recent release. concurrent-ruby 1.3.8 went up on July 19th, the same day SleeperGem's last gem did:

Gemfile	resolves to
`source "https://rubygems.org"`	concurrent-ruby 1.3.8 (2 days old)
`source "https://rubygems.org", cooldown: 7`	concurrent-ruby 1.3.7

It also fails closed. If nothing in the registry is old enough to satisfy your cooldown, Bundler does not quietly install the newest version anyway. I forced that case with an absurd window, cooldown: 36500, about a hundred years, against concurrent-ruby: it refused and told me what it held back, 79 versions excluded by the cooldown setting; pass --cooldown 0 to bypass. A guard that gives up silently when it cannot be satisfied is worse than no guard, because you think you have one.

Cooldown is unset by default, so if you never added that line, June changed nothing for you. None of the SleeperGem coverage I can find mentions that the feature exists.

What it doesn't buy you

Cooldown is a delay, not a defense. It works here because this attacker was loud and got caught in days. Against a version that ages quietly for three weeks, seven days of patience buys nothing.

It also does nothing about the actual hole. Neither Aikido nor StepSecurity says how the accounts were taken over. No vector, no phishing story, no statement about MFA in either direction. So every "this is why we need mandatory 2FA" reply is guessing, and mandatory MFA on RubyGems kicks in at 180 million downloads anyway. These gems are at 0.32% and 0.008% of that. It was never going to apply.

RubyGems built the right thing early and left it switched off. Go switch it on.

Rails already ships class_names. I built clsx anyway.

Leonid Svyatov — Tue, 21 Jul 2026 14:00:00 +0000

When I published a little gem for conditional CSS classes two years ago, the first comment was Adrien Poly asking the obvious thing: "What is the main difference with rails class_names helper?" My honest reply at the time: I didn't know class_names existed. I had written a gem for something Rails already shipped.

So I went and looked, guessed the difference was performance, and left it there. That answer bugged me for two years. Here is the real one.

class_names is a good view helper. It also only ships with ActionView, it spills a few inputs, it is slower than it needs to be, and it has no idea that px-2 and px-4 are the same knob. None of those matter until they do. When they did, for me, the fix turned one small Rails gem into two: clsx-ruby, a framework-agnostic core, and clsx-rails, a thin adapter over it.

This is the tour I wish I could have given Adrien in that comment thread.

First, credit where it is due

If you are on Rails 6.1 or later, you can build a class string conditionally today, no gems:

<%= tag.div class: class_names("btn", "btn-primary", active: @active) do %>
  Click me
<% end %>

class_names is a public alias for token_list in ActionView::Helpers::TagHelper. It takes strings, arrays, and hashes, splits on whitespace, drops falsy values, dedups the tokens, and hands back an HTML-safe string. For the everyday cases it is genuinely fine, and clsx agrees with it token for token:

require "clsx"
require "action_view"
# In an ERB template you call class_names(...) bare; here we mix it into an object.
view = Object.new.extend(ActionView::Helpers::TagHelper)

view.class_names("a", "b")                 # => "a b"
Clsx["a", "b"]                             # => "a b"

view.class_names(foo: true, bar: false)    # => "foo"
Clsx[foo: true, bar: false]                # => "foo"

view.class_names("a b", "b c")             # => "a b c"   (dedups across tokens)
Clsx["a b", "b c"]                         # => "a b c"

view.class_names("a", ["b", ["c"]])        # => "a b c"   (flattens nesting)
Clsx["a", ["b", ["c"]]]                    # => "a b c"

So if that is all you need, you need nothing. Use the built-in. I mean it.

The rest of this post is about the four places that "all you need" runs out.

Reason 1: it comes bundled with ActionView

class_names is a method on ActionView::Helpers::TagHelper. It does not actually need a live view, no request, no output buffer. It needs the module. But the module is part of ActionView, so to join two strings in a Sinatra app or a plain service object, you load a whole view framework and mix it in by hand:

# In a plain object with nothing required, class_names is not defined:
class_names("a", active: true)   # => NoMethodError

# You pull ActionView in and extend the module onto an object:
require "action_view"
view = Object.new.extend(ActionView::Helpers::TagHelper)
view.class_names("a", active: true)   # => "a"

That is the itch that started the split. I had put the class builder inside a Rails gem because Rails is where I was working that week. Then I wanted the same thing in a Phlex component, and in a plain presenter object, and reaching for ActionView to get it felt absurd. There is nothing Rails-specific about joining class names. So I pulled the logic into clsx-ruby, one file, about 130 lines, zero runtime dependencies, and left clsx-rails as a shim on top:

require "clsx"

is_active, is_disabled = true, false
Clsx["btn", "btn-primary", active: is_active, disabled: is_disabled]
# => "btn btn-primary active"

Reason 2: empty results, and what happens on garbage

class_names and clsx agree on the common cases. The one difference I lean on daily is what they return when nothing applies:

view.class_names(nil, false)   # => ""    (renders class="")
Clsx[nil, false]               # => nil   (Rails tag helpers skip it)

Rails skips a nil class attribute, so Clsx[...] never renders an empty class="" on a component that had nothing to add. class_names gives you "", which renders.

There is one honest point the other way. class_names returns an html_safe string; clsx returns a plain String. Inside a class: attribute that is a wash, Rails escapes the value either way and class tokens have nothing to escape. If you interpolate clsx output raw somewhere else, it is a normal string and gets escaped like one, which is the safe default, not a footgun. But if you specifically want html_safe output, class_names hands it to you and clsx does not.

The rest is robustness. Neither of these inputs is something you write on purpose, but a helper somewhere eventually hands the builder something weird, and the two disagree on what to do with it:

# A complex value used as a hash key.
view.class_names([{ foo: true }, "bar"] => true)  # => "[{foo: true}, &quot;bar&quot;]"
Clsx[[{ foo: true }, "bar"] => true]              # => "foo bar"

# An uncalled lambda and a stray boolean.
view.class_names(proc {}, true)  # => "#&lt;Proc:0x...&gt; true"   (escaped into your markup)
Clsx[proc {}, true]              # => nil

class_names stringifies whatever it gets and escapes it into the attribute; clsx resolves a complex key recursively and ignores a bare Proc or true. When an admin_link helper accidentally hands you an uncalled lambda, clsx drops it and class_names prints a Proc's address into your HTML. (There is also a cosmetic gap: class_names(" a\tb ") keeps a leading empty token, " a b"; clsx normalizes to "a b". Browsers ignore the extra space, so this one is tidiness, not a bug.)

The full vocabulary

The name is a homage: clsx-ruby is modeled on lukeed's clsx, the tiny JavaScript package, so the argument model lines up with what React developers already know. Since the differences above are really about what counts as a class and what counts as truthy, here are the rules in one place. clsx takes strings, symbols, numbers, hashes, arrays, and any nesting of those:

Clsx["foo", true && "bar", "baz"]          # => "foo bar baz"
Clsx[:foo, :"bar-baz"]                      # => "foo bar-baz"
Clsx[1, 2, 3]                               # => "1 2 3"
Clsx[["foo", nil, false, "bar"]]            # => "foo bar"
Clsx["foo", ["bar", { baz: false }, ["hi", ["there"]]]]
# => "foo bar hi there"

A hash includes each key whose value is truthy, in declaration order:

Clsx[foo: true, bar: false, baz: 2 > 1]   # => "foo baz"

The one rule that trips up people coming from JavaScript: in Ruby only false and nil are falsy. So 0, "", [], and {} are all truthy and all keep their key.

Clsx["foo" => 0, bar: []]   # => "foo bar"

And two conveniences the JS clsx does not have. Duplicates are removed even across multi-token strings, and an empty result is nil, not "":

Clsx["foo bar", "foo"]   # => "foo bar"
Clsx["   "]              # => nil

Every line above is a real result. bundle add clsx-ruby, drop them into a REPL, and check.

Reason 3: it is slower, and here is the honest version of that

clsx is faster than class_names per call. I reproduced it against the real ActionView helper (not a stand-in), timing only the cases where both produce identical output, on Ruby 4.0.6 and an M1 Pro:

Scenario	clsx-ruby	Rails `class_names`	Speedup
Token	5.1M i/s	674K i/s	7.5x
Long utility	572K i/s	116K i/s	4.9x
Utility string	1.2M i/s	248K i/s	4.9x
Multiple strings	1.4M i/s	334K i/s	4.1x
String array	1.2M i/s	307K i/s	4.0x
Hash	1.5M i/s	475K i/s	3.2x
String + hash	1.0M i/s	365K i/s	2.9x

That table is one representative run; the geometric mean held around 4x across three. The interesting number is not the 7.5x on a lone token, which is the least realistic input anyone would reach for a builder to handle, it is the 2.9x on the busiest, most Tailwind-like input. The speedup shrinks as the work grows, so the low end is the honest one.

A caveat on that gap. The gem's README quotes a more conservative 2 to 4x, because it benchmarks against a dependency-free replica of class_names. Part of the extra margin here is not a faster join, it is work clsx skips: class_names builds an html_safe buffer and un-escapes HTML on every call, and my identical-output filter compares string content, not that safety step. So the pure algorithm-to-algorithm number is the README's 2 to 4x; the wider figure is end-to-end against the real helper, which is what a Rails view actually pays. The gem ships its benchmark; run it yourself.

Now the honest part. This will almost never make a page faster. A class builder runs a handful of times per request, and your render time lives somewhere else entirely: allocations, HTML escaping, partial lookup, the N+1 you have not found yet. A 4x speedup on 0.1% of the work rounds to nothing.

Where it actually shows up is call count. Render a table with 5,000 rows and three conditional-class calls each, and now the helper runs 15,000 times in one response. That is the case where "4x faster per call" stops being a micro-benchmark and starts being real milliseconds. If your views do not do that, treat the speed as a nice-to-have and pick clsx for the other three reasons.

Reason 4: it cannot merge Tailwind classes

This is the one neither class_names nor plain clsx can touch:

view.class_names("px-2", "px-4")   # => "px-2 px-4"
Clsx["px-2 px-4"]                  # => "px-2 px-4"

Both keep both classes, because neither knows that px-2 and px-4 are the same knob set twice. And in Tailwind, shipping both is a bug you cannot see. The winner is not the last class in the attribute, it is whichever rule Tailwind emitted later in the compiled stylesheet, and Tailwind orders by its own scale, not by what you wrote. That is deterministic, so it will not flip between machines, but it is also not your call: you ship a silently dead class, and which one dies is decided by Tailwind's internal ordering rather than your intent.

If you have written React with Tailwind, you already know the fix, even if you have never looked at it. That cn(...) helper everyone copies out of shadcn/ui is literally twMerge(clsx(inputs)): clsx builds the string, tailwind-merge collapses the conflicts so the class you wrote last is the one that survives. clsx does the same, split into two functions so you only pay for merging when you ask for it.

The merge is opt-in. clsx-ruby stays dependency-free; you add the tailwind_merge gem and wire it up once:

# Gemfile
gem "tailwind_merge"

# config/initializers/clsx.rb
require "clsx/tailwind_merge"
Clsx.merger = TailwindMerge::Merger.new

That adds twm (and Twm[], and Clsx.twm) alongside clsx. clsx and cn stay pure; only twm merges, and the last one you wrote wins, whichever order you wrote it in:

Twm["px-2 px-4"]                          # => "px-4"
Twm["px-4 px-2"]                          # => "px-2"   (written order, not Tailwind's)
Twm["p-4", "p-2", "bg-red", "bg-blue"]    # => "p-2 bg-blue"
Clsx["px-2 px-4"]                         # => "px-2 px-4"   (unchanged)

That second line is the whole point: your written order becomes authoritative, which is exactly what raw Tailwind does not honor. It is also group-aware, so it only collapses classes that genuinely conflict. px-3 and pr-4 set different things, so both survive, but px-3 is the broader knob (it includes padding-right), so written last it wins:

Twm["px-3 pr-4"]   # => "px-3 pr-4"   (different groups, both kept)
Twm["pr-4 px-3"]   # => "px-3"        (px-3 covers pr, and it came last)
Twm["px-[13px] px-[14px]"]   # => "px-[14px]"   (arbitrary values too)

And because twm takes the same inputs as clsx, you get the conditional syntax and the merge in one call:

Twm[["px-2", "rounded"], "px-4", "px-6": active]   # => "rounded px-6"   (active)

You set Clsx.merger once at boot and read it per request. Merging is real work: tailwind_merge parses each class into its group, which is why it keeps a result cache and why it is worth doing only when asked. That is also why I kept clsx and twm separate. An early prototype had a global switch that routed every call through the merger (never shipped, so do not go looking for it), and I talked myself out of it: most calls have no conflict to resolve, so paying the merge cost on all of them to help a few is the wrong default.

The merger slot is pluggable, it just has to respond to merge. The default is Garen Torikian's tailwind_merge, which I use enough that I have two PRs in it, one making that result cache thread-safe and one speeding up the hot path, both shipped in its 1.5.2. If you need more throughput, a Rust-backed alternative (tail_merge) exists, though confirm its Tailwind version support against your setup.

Which call do I reach for?

There are a few ways in, which looks like more than it is. They all run the same code.

Clsx[...] and Cn[...] (the bracket form) work anywhere, no setup. This is what I use in plain Ruby.
In Rails views (ERB, HAML, or Slim), clsx-rails gives you clsx(...) and cn(...) as bare helpers, no include.
In a ViewComponent, a Phlex component, or any object, include Clsx::Helper once and you get clsx/cn (and twm if you wired it up) as methods.
Clsx.clsx(...) / Clsx.cn(...) are the module-method form for when you do not want either.

cn is just a shorter alias for clsx. Pick whichever reads better in the line.

Using it outside Rails

The whole point of the split is that none of this needs Rails. In a Phlex component you include the helper once and call it like any method:

require "phlex"
require "clsx"

class Badge < Phlex::HTML
  include Clsx::Helper

  def initialize(color: :blue, pill: false, class: nil)
    @color = color
    @pill = pill
    @html_class = binding.local_variable_get(:class)  # `class` is a keyword
  end

  def view_template(&block)
    span(class: clsx("badge", "badge-#{@color}", @html_class, pill: @pill), &block)
  end
end

Badge.new(color: :red, pill: true, class: "badge ml-2").call { "New" }
# => <span class="badge badge-red ml-2 pill">New</span>

One line in there is pure Ruby trivia. You can name a keyword argument class:, but you cannot read it back as class (it is a reserved word, so @html_class = class is a syntax error). binding.local_variable_get(:class) is the escape hatch that fetches the local by name.

The payoff is the cross-argument dedup: badge appears once even though the caller passed it and the component added it too. That is the thing you actually want when a component merges its classes with a caller's, and it is tedious to write by hand every time. The same include works in a ViewComponent base class, a Sinatra route, or a bare presenter.

Phlex, for the record, has its own answer for the simple case: class: accepts an array and compacts falsy entries, and its mix helper merges attribute hashes. Reach for clsx when you want the hash-conditional syntax or the cross-argument dedup, and twm when you want Tailwind conflicts resolved, which none of Rails, ViewComponent, or Phlex do on their own.

What changed since 2024, and do you have to migrate

The old post covered clsx-rails around v1: the basic string, array, and hash syntax, Rails only. Since then:

v2 (2025) rewrote the algorithm for a 2 to 5x speedup and dropped Rails 6.1 and 7.0.
v3 (2026) extracted the engine into clsx-ruby and made clsx-rails a thin adapter over it. It raised the floor to Ruby 3.2+ and Rails 7.2+.
v3.1 added the twm Tailwind merge through clsx-ruby 1.2.

If you are on an older clsx-rails, the upgrade is quiet. The breaking changes in v3 are the Ruby and Rails version floors, not the helpers. Same clsx and cn, same output. The one snag: Clsx::VERSION now reports the clsx-ruby core version, and the adapter's own version moved to Clsx::Rails::VERSION, so anything that read the old constant needs a one-line update. New since you last looked: everything runs outside Rails now, and twm exists.

When to use something else

clsx builds a class string. That is the whole job. If your problem is bigger, it is the wrong tool:

You just need conditional classes in a Rails view and none of the four reasons bite? Use class_names. It is already there.
You want a variant system, the size: :lg, intent: :danger to full-class-list mapping React people know as CVA? That is class_variants, a different and larger idea, and it can lean on a merger like twm for the final conflict pass.
You want another plain conditional-class helper to compare against? klassnames is the closest same-purpose gem for Rails; it does the conditional join without the framework-agnostic core, the nil return, or the Tailwind merge.
You want the smallest possible dependency and only ever pass plain strings? You can hand-roll a compact.join(" ") and skip the gem. You lose dedup, the hash syntax, nil handling, and the merge, but if you never wanted those, that is a fair trade.

For everything between "join two strings" and "design a variant DSL," which is most of what view code actually does, clsx is the size that fits.

class_names builds class strings inside a view. clsx builds them anywhere, keeps the weird inputs from leaking, and knows what to do when two Tailwind utilities disagree. That is the whole difference, and now it is one bundle add away.

Learn Big O by measuring it, in Ruby

Leonid Svyatov — Mon, 20 Jul 2026 14:00:00 +0000

A very common way Ruby code gets slow at scale hides in a line that looks harmless:

records.select { |r| seen.include?(r.id) }

If seen is an Array, that is O(n²). Every one of the n records triggers an include? that scans up to n elements. It runs fine on the hundred rows you tested and falls over on the hundred thousand you didn't. You can see this coming, and you don't have to squint at the code to do it. You can measure the growth rate directly and watch it bend upward.

That is what this post is about. Not the theory of Big O from a chart of curves, but Big O as something you can put on a clock. We are going to take real Ruby, run it on inputs that keep doubling, time each run, and let the complexity class fall out of the numbers, one at a time. By the end you will have measured O(1), O(log n), O(n), O(n log n), O(n²), and O(2ⁿ) with your own hands. And you will know exactly when the measurement is lying to you, because that turns out to be the harder and more useful half.

I went looking for a BigO.measure { some_code } method, half expecting to build it. It already exists, it has been sitting on RubyGems since 2020, and the interesting part is how confidently it can be wrong.

The whole idea: double the input, watch the clock

Big O describes how the work grows as the input grows. Not how long something takes, but how the time scales. O(n) means double the input and the work roughly doubles. O(n²) means double the input and the work goes up about fourfold. O(1) means the input size doesn't matter at all.

That "double the input" is the whole measurement technique, and it is older than any gem. It is called the doubling hypothesis, and it is exactly what Princeton teaches in its algorithms course. Run your code at some size n, then at 2n, and look at the ratio of the two times:

Time ratio when you double n	Growth class
stays flat (~1×)	O(1)
creeps up by a constant	O(log n)
~2×	O(n)
a bit more than 2×	O(n log n)
~4×	O(n²)
squares each step	O(2ⁿ)

If you do this across a wide range of sizes and fit the points to the curve time = a · n^b, the exponent b is the growth rate. Fit a straight line through the same points on log-log axes and its slope is that same b. That is the entire trick: measure at many sizes, fit a power curve, read the exponent. A linear algorithm gives b ≈ 1. A quadratic one gives b ≈ 2. Everything else lands somewhere you can read off a ruler.

There is a gem that does the fitting for you. Before we let it, let's do it by hand once, so nothing about the result is magic.

Every class, measured

The tool is benchmark-trend by Piotr Murach. Add it to a Gemfile with gem "benchmark-trend" and bundle install. It gives you two pieces: Benchmark::Trend.range to build a geometric ladder of sizes (with ratio: 4, each size is four times the last: 1000, 4000, 16000, and so on up to the max), and Benchmark::Trend.infer_trend to run your code at each size and fit the curves.

One thing matters before we start, and it is the mistake everyone makes first. infer_trend times the entire block you give it. If you build your test data inside that block, you are timing the setup too, and the setup usually has its own complexity that swamps what you meant to measure. So build the input for each size first, then time only the operation. Here is a small helper that does exactly that:

require "benchmark/trend"

# sizes:   the geometric range of input sizes
# prepare: builds the input for a given size, once, before timing
# work:    the operation whose growth we're measuring
def measure(sizes, prepare:, &work)
  inputs = sizes.map { |n| prepare.call(n) }

  trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |n, i|
    work.call(inputs[i], n)
  end

  r2 = fits[trend][:residual]      # how well the winning curve fit (R², 0 to 1)

  if trend == :exponential
    # A compounding curve has no polynomial exponent to read, so skip it.
    puts "best fit: #{trend}  (compounding growth)  R2=#{format('%.4f', r2)}"
  else
    b = fits[:power][:slope]       # the power-law exponent: our growth "ruler"
    puts "best fit: #{trend}  exponent b=#{format('%.2f', b)}  R2=#{format('%.4f', r2)}"
  end
end

Two blocks are in play here, and it helps to keep them straight. The one infer_trend calls receives (n, i), the size and its index, and uses i to pick the matching pre-built input. The block you write and pass to measure receives that prepared input as its first argument and the size n as its second, so you will see signatures like |array, n| below (and _n when a demo doesn't need the size). Either way, work.call(...) is the timed part, never the setup. Save this helper as measure.rb; every demo below opens with require_relative "measure", and each is a complete, runnable file once benchmark-trend is installed.

(repeat: 4 runs each size four times and averages, to smooth out noise.) Read two numbers out of every run. The best fit is the curve family the gem picked. The exponent b is the growth ruler: near 0 is flat, near 1 is linear, near 2 is quadratic. For an exponential curve there is no meaningful polynomial exponent, so the helper skips it and the family name carries the result.

O(1): the lookup that doesn't care how big the haystack is

Start with the class that feels like magic the first time you see it. A Hash lookup takes about the same time whether the Hash holds a thousand keys or a million:

require_relative "measure"

LOOKUPS = 200_000
sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)

measure(
  sizes,
  # Build a Hash of n keys, plus a fixed batch of keys to look up.
  prepare: ->(n) {
    hash = (1..n).to_h { |k| [k, true] }
    keys = Array.new(LOOKUPS) { rand(1..n) }
    [hash, keys]
  }
) do |(hash, keys), _n|
  keys.each { |k| hash[k] } # always LOOKUPS lookups, no matter how big the Hash
end

The batch is a fixed 200,000 lookups at every size. The Hash grows from a thousand keys to a million; the amount of work does not. Run it:

best fit: linear  exponent b=0.26  R2=0.9976

The exponent is 0.26, way below linear's 1. Flat-ish. It is not exactly 0, and the leftover is the machine, not the algorithm: most likely the Hash spilling out of CPU cache as it grows, so each lookup gets a little slower, though a single run can't cleanly separate that from noise or GC.

This is also the shakiest measurement in the post, and worth knowing that up front. Rerun it and the exponent bounces around 0.2 to 0.3, and on a busy machine the fitter can even misname the family as exponential, because a flat line has no real trend for it to lock onto, so noise wins. That instability is itself the fingerprint of constant time. Hold the thought, because it is our first hint that the clock measures more than complexity. We will come back to it.

O(log n): binary search halves the problem each step

Logarithmic growth is the one people struggle to picture. It means each step throws away half of what is left, so doubling the input adds just one more step. Binary search on a sorted Array is the textbook case, and Ruby has it built in as Array#bsearch:

require_relative "measure"

SEARCHES = 200_000
sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)

measure(
  sizes,
  prepare: ->(n) {
    array   = (1..n).to_a
    targets = Array.new(SEARCHES) { rand(1..n) }
    [array, targets]
  }
) do |(array, targets), _n|
  targets.each { |t| array.bsearch { |x| x >= t } } # ~log2(n) comparisons each
end

best fit: power  exponent b=0.12  R2=0.9906

An exponent of 0.12: nearly flat, and notice it came in below the O(1) run's 0.26, not above. That is not a mistake, it is the lesson arriving early. Logarithmic growth is so slow that on a ruler measuring polynomial degree it sits right down on the floor with constant time, and here noise in the O(1) run even pushed it higher than the log one. Going from a thousand to a million elements, a 1000× jump, only about tripled the depth of each search. The takeaway to bank: O(1) and O(log n) both read as "small exponent, nearly flat," and timings alone cannot reliably tell them apart or even order them. We will make that a rule later.

O(n): the linear scan from the opening

Now the line that started this post. Array#include? walks the array element by element until it finds a match. Search for something that isn't there and it has to touch all n elements:

require_relative "measure"

sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)

measure(
  sizes,
  prepare: ->(n) { (1..n).to_a }
) do |array, n|
  array.include?(n + 1) # absent value, so the scan can't stop early
end

best fit: linear  exponent b=0.96  R2=1.0000

Exponent 0.96, an R² of 1.0, and this time the gem named the family linear outright. Double the array and the scan takes twice as long. This is the shape hiding inside that select from the opening, and in a moment we will see what happens when you nest it.

O(n log n): sort, and a first look at trouble

Sorting is the workhorse of the "slightly worse than linear" class. Ruby's Array#sort is a quicksort variant, average O(n log n):

require_relative "measure"

sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)

measure(
  sizes,
  prepare: ->(n) { (1..n).to_a.shuffle } # fresh shuffle so each sort starts unsorted
) do |array, _n|
  array.sort
end

best fit: power  exponent b=1.09  R2=0.9998

Look closely, because this is the crux of the whole post. The exponent is 1.09. Not 2. Barely above the linear scan's 0.96. Sorting is genuinely O(n log n), meaningfully more work than a linear pass, and the measurement can barely tell the difference. The log factor is nearly invisible to a power fit. That is not a flaw in this gem; it is a limit of the technique itself, and it has a whole section coming. For now, just notice that O(n) and O(n log n) landed almost on top of each other: 0.96 and 1.09.

O(n²): the accidental one

Here is the opening bug, built on purpose. Filter n rows, and for each row do an include? scan over an n-element Array. That is n rows times an n-element scan:

require_relative "measure"

sizes = Benchmark::Trend.range(500, 8_000, ratio: 2) # smaller: n² gets big fast

measure(
  sizes,
  prepare: ->(n) {
    rows = (1..n).to_a
    seen = (n + 1..2 * n).to_a # values that are absent, forcing a full scan
    [rows, seen]
  }
) do |(rows, seen), _n|
  rows.select { |r| seen.include?(r) }
end

best fit: power  exponent b=1.99  R2=1.0000

Exponent 1.99, near enough to 2. That is quadratic, plain as day, and it is the number that separates a page that loads instantly from one that times out. Swap that Array for a Set and the exponent drops back toward 1, because a Set is Hash-backed and its include? is average O(1). That is why a Set is the right structure for a membership check, and we will gate exactly this difference in CI later.

O(2ⁿ): the one that ends the party

Exponential growth is the cliff. Each +1 to the input roughly doubles the work. The classic offender is naive recursive Fibonacci, where every call spawns two more:

require_relative "measure"

def fib(n) = n < 2 ? n : fib(n - 1) + fib(n - 2)

# Exponential workloads need small, closely-spaced sizes, not a wide sweep.
# infer_trend accepts any array of sizes, not just Trend.range output.
sizes = (20..32).step(2).to_a

measure(sizes, prepare: ->(n) { n }) do |n, _i|
  fib(n)
end

best fit: exponential  (compounding growth)  R2=0.9999

The gem names it exponential and I skip the power exponent here, because for a compounding curve the polynomial ruler is meaningless. This is why fib(50) would outlast your patience while fib(30) returns instantly. The sizes only go to 32 for a reason.

Here is the whole ladder from one run, so you can see the ruler climb:

O(1)  Hash#[]          best fit: linear  exponent b=0.26  R2=0.9976
O(log n)  bsearch      best fit: power  exponent b=0.12  R2=0.9906
O(n)  include?         best fit: linear  exponent b=0.96  R2=1.0000
O(n log n)  sort       best fit: power  exponent b=1.09  R2=0.9998
O(n^2)  select+incl    best fit: power  exponent b=1.99  R2=1.0000
O(2^n)  fib            best fit: exponential  (compounding growth)  R2=0.9999

Your exact numbers will differ, because this is a stopwatch on a real machine. Even the order at the flat end can wobble, as O(1) and O(log n) just did. What holds is the climb once there is real growth to see: near-flat, then a linear ramp near 1, then a quadratic wall near 2, then off the exponential cliff. Here is the same story as curves:

The one-call version, and its rough edges

You do not need the helper. The core of benchmark-trend is a single call, and it is worth seeing raw:

require "benchmark/trend"

sizes  = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)
arrays = sizes.map { |n| (1..n).to_a }

trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |_n, i|
  arrays[i].include?(-1) # absent value, so the scan is O(n)
end

puts "best fit: #{trend}"
puts "residual (R2): #{fits[trend.to_sym][:residual].round(4)}"

best fit: linear
residual (R2): 0.9999

infer_trend returns the winning family as a Symbol and a Hash of every fit it tried. That is genuinely close to the BigO.measure { } I went looking for. But it has three edges worth knowing before you trust its output, and none of them are in the README's happy path.

It fits four curve families, and quadratic isn't one of them. The candidates are exponential, power, linear, and logarithmic. There is no dedicated n² model and no n log n model. This is why we read polynomial degree off the power fit's exponent instead of expecting a name like "quadratic." An exponent near 2 is how quadratic shows up. If you were hoping the tool would just print "O(n²)," it can't, and now you know why.

The residual is R², and higher is better. In the output above, residual: 0.9999 means the linear curve explained almost all the variance in the timings. Values run from 0 (useless) to 1 (perfect). Treat anything under about 0.9 as "the fit didn't take, don't trust the label." Strictly, the gem picks the winner on R² and a small penalty for model complexity, so a fancier curve has to earn its win rather than edge ahead on a rounding error, but R² is the number you read.

The human-readable trend string has a bug. Every fit carries a pretty-printed formula, and for a power fit it prints its two numbers in the wrong slots. Here is a full run against sort, which fits a power law, printing the formula next to the real values pulled from the Hash:

require "benchmark/trend"

sizes  = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4)
arrays = sizes.map { |n| (1..n).to_a.shuffle }

_trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |_n, i|
  arrays[i].sort
end

power = fits[:power]
puts "printed string:   #{power[:trend]}"          # what the gem shows you
puts "slope (exponent): #{power[:slope].round(3)}" # the REAL growth exponent
puts "intercept (coef): #{power[:intercept]}"      # the REAL coefficient

printed string:   1.09 * x^0.00
slope (exponent): 1.086
intercept (coef): 3.55684051103109e-08

The string reads 1.09 * x^0.00, which looks like an exponent of zero, a flat line. But the real exponent is 1.086, sitting in the slope field, and the tiny coefficient is in intercept. The formatter swapped them. The gem's own README shows the same swapped shape in its example output, so this is not a fluke on my machine. The lesson is simple: read :slope and :intercept from the Hash, and ignore the pretty string.

Those edges aside, the fitted curve buys you something useful: it can project a runtime at a size you never ran. Benchmark::Trend.fit_at takes the slope and intercept from a fit and evaluates the curve at any n. Feed it the O(n²) filter's power fit and ask what a hundred thousand rows would cost:

power = fits[:power] # from the O(n²) measurement above
at = Benchmark::Trend.fit_at(:power, slope: power[:slope],
                                     intercept: power[:intercept], n: 100_000)
puts "projected time at n=100_000: #{at.round(2)} s"
# => projected time at n=100_000: 31.3 s

The absolute seconds are machine-specific and will swing between runs, so trust the order of magnitude, not the decimal. That is the whole reason complexity is worth knowing: an exponent near 2 means roughly ten times the rows costs a hundred times the time, and now you can see the wall before you hit it in production.

One more thing to know up front, not a bug but a fact. benchmark-trend last shipped version 0.4.0 in March 2020, and its RSpec companion rspec-benchmark shipped 0.6.0 two days later. Neither has had a release since. They still install and run cleanly on Ruby 4.0, which is what every example here runs on, but you are adopting stable, dormant code, and that is worth a conscious choice.

Where the stopwatch lies

Everything so far makes measurement look easy. It isn't, and the gap between "I measured it" and "I know its complexity" is where people get burned. Four ways the clock misleads you.

It measures Big Theta, not Big O. This is the subtle one. Big O is a worst-case upper bound, a promise about the worst input the algorithm could ever face. A stopwatch can't measure a promise. It measures what actually happened on the inputs you chose. Feed quicksort already-sorted data and you might see one shape; feed it its pathological worst case and you'll see another. What you get back is the observed order of growth on your workload, which theorists call Big Theta, not the worst-case Big O.

The Python equivalent of this technique, the big_O package, says so flatly in its own docs: "Strictly speaking, we're empirically computing the Big Theta class." Every demo above quietly chose its inputs. The include? scan searched for an absent value on purpose, to force the full-length worst case. Change that decision and you change the number.

It is blind to log factors. Remember sort landing at 1.09, right next to the linear scan's 0.96? That is not bad luck, it is arithmetic. When you double the input, an O(n) algorithm's time doubles and an O(n log n) algorithm's time slightly-more-than-doubles, and "slightly more" is nearly invisible against measurement noise. Princeton's own course notes put it bluntly: you "cannot identify logarithmic factors with the doubling hypothesis." So a power fit cannot cleanly separate O(n) from O(n log n). If your exponent lands around 1, you have learned it is roughly linear, and to tell linear from linearithmic you have to go read the code. The clock won't do it for you.

A too-narrow range invents an answer. Watch the same linear scan, measured over a tiny range of sizes and then a wide one:

op    = ->(array, n) { array.include?(n + 1) } # same O(n) scan both times
build = ->(n) { (1..n).to_a }

puts "narrow range (100..800):"
measure(Benchmark::Trend.range(100, 800, ratio: 2), prepare: build, &op)

puts "wide range (1_000..1_000_000):"
measure(Benchmark::Trend.range(1_000, 1_000_000, ratio: 4), prepare: build, &op)

narrow range (100..800):
best fit: constant  exponent b=0.60  R2=1.0000
wide range (1_000..1_000_000):
best fit: linear  exponent b=0.96  R2=1.0000

Over 100 to 800 elements, a linear scan looks constant, with a perfect R² of 1.0 on the wrong answer. (constant here is not a fifth family; it is what the gem calls a linear fit whose slope came out flat at zero, and perform_constant later is that same zero-slope special case.) At those sizes the scan is so fast that fixed overhead drowns the actual growth. The high R² gives you false confidence in a false label. Only across a wide range, where the real work dominates, does the linear shape appear. The rule the research literature agrees on: your smallest size must be big enough that the operation itself, not the overhead around it, dominates the clock.

The machine leaks into the measurement. Garbage collection pauses, CPU cache behavior, other processes, JIT warmup: all of it lands in the timings. The usual teaching model says these effects only shift the constant factor and leave the exponent alone. Mostly true, but not a guarantee. Our own O(1) Hash lookup came back at exponent 0.26 instead of 0, most likely because its memory working set grew past the CPU cache. In a garbage-collected runtime, effects that scale with n can bend the exponent itself.

benchmark-trend fights back where it can: it uses a monotonic clock, runs GC.start before each size, and averages repeated runs when you pass repeat:. It does not warm up the code, though, and wall-clock timing in Ruby is noisier than the deterministic operation-counting the academic papers use. Measure the same thing twice and you will get two slightly different exponents. That is normal.

None of this makes the technique useless. It makes it a tool with a manual. You measure to build intuition and to catch regressions, and when two adjacent classes are ambiguous, you fall back to reading the code.

Gating complexity in CI

Measuring by hand teaches you the shapes. The payoff at work is different: catch the day someone turns your O(n) into an O(n²) without noticing. That is what rspec-benchmark is for. It wraps benchmark-trend in RSpec matchers, so you assert a growth class the way you assert anything else.

The matchers are perform_constant, perform_logarithmic, perform_linear, perform_power, and perform_exponential. There is no perform_quadratic, for the four-families reason from earlier; a quadratic is a perform_power whose exponent lands near 2. Here is a gate on the membership filter from the opening, pinned to a Set so it stays linear:

require "benchmark/trend"
require "rspec-benchmark"
require "set"

RSpec.configure { |c| c.include RSpec::Benchmark::Matchers }

SIZES = Benchmark::Trend.range(200, 3_200, ratio: 2)
ROWS  = SIZES.to_h { |n| [n, (1..n).to_a] }
SEEN_SET = SIZES.to_h { |n| [n, (n + 1..2 * n).to_a.to_set] }

RSpec.describe "membership filtering" do
  it "stays linear with a Set" do
    expect { |n, _i| ROWS[n].select { |r| SEEN_SET[n].include?(r) } }
      .to perform_linear.in_range(200, 3_200).ratio(2).sample(100).times
  end
end

Two details carry the weight. The block takes n, so the work has to scale with n: we key the pre-built inputs by size and look them up, exactly like the helper did, so we never time the setup. And in_range(min, max).ratio(r) rebuilds the same geometric ladder Benchmark::Trend.range would, which is why keying the data by n lines up. With SEEN_SET a Set, include? is average O(1), so filtering n rows costs O(n) total and the gate passes green.

Now regress it. Swap that Set back to a plain Array and keep the linear gate:

SEEN = SIZES.to_h { |n| [n, (n + 1..2 * n).to_a] } # Array, not Set

it "is supposed to stay linear (but doesn't)" do
  expect { |n, _i| ROWS[n].select { |r| SEEN[n].include?(r) } }
    .to perform_linear.in_range(200, 3_200).ratio(2).sample(100).times
end

The same filter is now O(n²), the gate goes red, and it names the class it actually found:

Failures:
  1) membership filtering is supposed to stay linear (but doesn't)
     Failure/Error: expect { |n, _i| ROWS[n].select { |r| SEEN[n].include?(r) } }
       expected block to perform linear, but performed power

That "expected linear, but performed power" is the regression caught before production. One honest warning, straight from the gem's own README: these matchers are "potentially flaky." They are timing-based, so a loaded CI machine can occasionally flip a borderline result. Keep them out of your normal suite. Tag them, give them their own run, and lean on them for the classes that are unambiguous, an O(n) that must not become O(n²).

When to reach for it, and when not

Empirical measurement is a teacher and a smoke alarm, not a proof. Reach for it to build a feel for a method you don't know: put Array#include?, Set#include?, and Hash#[] on the clock and the difference stops being abstract. Ruby's docs rarely state the complexity of built-in methods (bsearch is a rare one that spells out O(log n); include? and sort say nothing), so measuring is often how you find out. And reach for it to guard a hot path in CI, where a perform_linear gate on the endpoint that melted last quarter is cheap insurance.

Keep in mind what it does not measure: the constant factor. benchmark-trend tells you the shape of the curve, not which of two methods is faster at the size you actually run. That second question, "is a Set worth it for my 50 items," belongs to benchmark-ips or the stdlib Benchmark. The two are complementary, one for the growth, one for the wall-clock at a fixed size.

Then the boundaries. Don't reach for it to prove a worst-case bound; it measures the case you fed it. Don't trust it to split two adjacent classes; when the exponent sits near 1, the clock has told you everything it can, and the code has the rest.

Don't point it at IO, either. Every demo here is pure in-memory CPU work, which is where wall-clock inference behaves. A loop of database queries or network calls has its growth swamped by connection and IO variance, so the exponent turns to mush. For the classic N+1 query, count the queries, don't time the exponent.

And remember a worse Big O can still win at the sizes you actually run. For small n, constants and memory layout dominate, which is why hybrid sort implementations fall back to insertion sort on small chunks even though it is O(n²). Big O is the shape of the curve as n grows, not the winner at any single size. When it matters, measure the crossover for your own case.

So measure your code. Watch the exponent climb from a flat line to a linear ramp to a quadratic wall. Just keep one hand on the manual, because the clock will tell you a clean story, and sometimes the story is wrong.

Keeping code alive on a DOM you don't own: 12-year Chrome extension story

Leonid Svyatov — Fri, 17 Jul 2026 14:00:00 +0000

In April 2014 I wanted to sort posts on the Hacker News front page by points, by time, or by comments. Nothing I found did it without cluttering the page, so I wrote a tiny Chrome extension over a couple of days, uploaded it to the Web Store, and mostly stopped thinking about it for ten years.

I touched it exactly once in that decade, in 2019, to fix the selectors.

Then in March 2024 I rewrote it from scratch, with the old version still working fine: I wanted TypeScript, React, and tests, and Manifest v3 while I was in there. That's when I started actually maintaining it.

It's called Hacker News Sorted, it's now at v2.6.1, and it has one dependency that never appears in package.json: the exact HTML structure of the Hacker News front page. HN can change that structure any day, without a changelog, and they owe me nothing.

Sorting 30 rows of a table is a weekend project. This post is about everything else: the selector that survived a layout change and the one that didn't, the badge that tells users it's my fault, the GitHub Action that checks HN's HTML every morning, and the timestamps HN quietly rewrites.

The obvious question first: HN has an official API, so why scrape the DOM at all? Because the extension doesn't need data, it needs to rearrange the page you're already looking at. Every number it sorts by is already sitting in the rows, true timestamps included.

Fetching the same 30 items over the network would only add latency, a wider permission surface, and a privacy story to explain.

The selector war

HN's front page is one big <table>. Each story is three <tr>s, emitted in order: a title row, an info row (points, age, comments), and an empty spacer row. The natural way to grab them is nth-child arithmetic, and that part hasn't needed a single change since the 2024 rewrite:

// app/constants.ts (v2.6.1)
TITLE_ROWS: 'tr:nth-child(3n+1)',
INFO_ROWS: 'tr:nth-child(3n+2)',
SPACER_ROWS: 'tr:nth-child(3n+3)',

Each 3n+k picks every third row from offset k: titles at 1, 4, 7, info rows at 2, 5, 8, spacers at 3, 6, 9. The pattern assumes nothing non-story slips between the rows. HN's one exception, the "More" link at the bottom, sits after all 30 stories, so it never shifts the count above it.

The trap is what those selectors run against. Until March 2026, my two outer anchors were absolute paths through HN's table soup:

// app/constants.ts, the anchors before March 2026 (v2.3.1)
CONTROL_PANEL_PARENT:
  'body > center > table > tbody > tr:nth-child(2) > td > table > tbody > tr > td:nth-child(3)',
TABLE_BODY:
  'body > center > table > tbody > tr:nth-child(4) > td > table > tbody',

Every nth-child(N) in there is a bet that HN will never insert a row above row N. On March 11, 2026, HN added a logo row to its outer table and won the bet. Both anchors stopped matching, and the extension didn't crash or throw. It just silently did nothing, on every user's machine at once.

I committed a hotfix at 17:54 that day: bump the shifted indices by one. Committed, not delivered: an extension fix reaches users only after the Chrome Web Store review approves the update, so every hour of my reaction time has Google's review time stacked on top of it.

Then I sat with the diff and realized I was patching the symptom. The real problem was anchoring to positions when HN's markup is full of names that have barely moved in two decades (.pagetop is in the earliest Wayback Machine capture of HN, from 2007). At 18:47, 53 minutes after the hotfix, I replaced the positional paths with semantic anchors.

My first pass at that was #hnmain tr:has(.hnname) > td:last-child. (:has() matches an element by what it contains, the one relational selector CSS gives you.) It felt clever and it was wrong: tr:has(.hnname) matches any row with .hnname anywhere inside it, and HN nests tables inside tables, so an outer wrapper row matched along with the nav row it contains.

The sort menu injected itself above the page header. The version that stuck, two days later, pins every step with direct-child combinators:

// app/constants.ts (v2.6.1)
CONTROL_PANEL_PARENT: '#hnmain tr:has(> td > .pagetop > .hnname) > td:last-child',
TABLE_BODY: '#hnmain #bigbox > td > table > tbody',

Read the first one aloud: the cell next to the nav that contains the site name. It no longer cares how many wrapper tables HN nests around that row, and it can't accidentally match a parent, because every hop is >.

I want to be honest about what this buys. These are still bets. td:last-child is positional; the tbody chain still encodes nesting. The difference is what the bets are on: names HN's own stylesheet depends on, plus a few explicit local hops, instead of a count of rows in a table I can't see change.

HN renaming #hnmain would break me; HN renaming #hnmain would also break HN's own CSS, so we'd at least go down together. And the new anchors have survived exactly zero HN layout changes so far, because HN hasn't shipped one since. The positional paths survived two years before losing. Ask me in 2028.

One boundary on all of this: it works because HN's markup is unusually stable and hand-named. On a bundler-built SPA with hashed class names there are no names worth anchoring to, and you're down to ARIA roles, text content, and luck.

When the selectors fail anyway

So v2.4.0 added the assumption that the new anchors will eventually lose too. The failure mode that scares me isn't a selector that throws; it's one that matches nothing while I have no way to know.

The content script waits for HN's DOM with a MutationObserver on document.body (the browser API that calls you back whenever the DOM changes), then runs a sanity check before injecting anything:

// content.tsx (v2.6.1)
const verifyAndInject = (parent: HTMLElement, resolve: (el: HTMLElement) => void): boolean => {
  if (!getTableBody()) {
    setLayoutStatus(false);
    return false;
  }
  setLayoutStatus(true);
  resolve(injectRootElement(parent));
  return true;
};

The content script hands Plasmo (the extension framework) a Promise that will deliver the element to render into; the resolve here is that Promise's resolve.

If the panel's parent shows up but the story table doesn't, the layout has shifted in a way I can't handle, and setLayoutStatus(false) writes a flag to chrome.storage.sync. A 3-second timeout covers the other case: if the parent never appears at all, same flag, and the panel never renders.

The badge itself can't be painted from the content script: only the extension's background service worker may call chrome.action, and chrome.storage is the bridge between those two worlds. Here's the entire background file, 19 lines:

// background.ts (v2.6.1)
import { SETTINGS_KEYS } from '~app/constants';

function updateBadge(ok: boolean) {
  chrome.action.setBadgeText({ text: ok ? '' : ':(' });
  chrome.action.setBadgeBackgroundColor({ color: '#E05050' });
  chrome.action.setBadgeTextColor({ color: '#FFFFFF' });
}

// Restore badge state on service worker restart
chrome.storage.sync.get(SETTINGS_KEYS.LAYOUT_OK, (result) => {
  if (result[SETTINGS_KEYS.LAYOUT_OK] === false) updateBadge(false);
});

// React to layout status changes
chrome.storage.sync.onChanged.addListener((changes) => {
  if (SETTINGS_KEYS.LAYOUT_OK in changes) {
    updateBadge(changes[SETTINGS_KEYS.LAYOUT_OK].newValue !== false);
  }
});

Users see a red :( on the extension icon, and the popup shows a banner: "Sorting temporarily unavailable :( Hacker News appears to have changed its page layout. We're aware, and a fix is on the way." A broken extension that tells you it's broken gets a bug report. A silent one gets an uninstall.

The two-part structure of that file is Manifest v3 discipline. An MV3 service worker is killed after about 30 seconds of idle, and every global variable dies with it, so the flag's only real home is chrome.storage.

The listener at the bottom reacts to changes while the worker happens to be alive (anything but an explicit false counts as healthy). The get at the top runs every time Chrome starts the worker fresh, and it's what puts the badge back after the cases where Chrome resets badge state entirely, like a browser restart or an extension reload.

Write state assuming your process is already dead; read it back assuming you just woke up with amnesia.

Scope, for the record: the script matches every news.ycombinator.com page except item pages, which get a separate content script for the comment features.

One wart: at v2.6.1 the check has two false positives. Pages with no story list at all (your profile, the submit form) wait 3 seconds, find no table, and flip the flag.

And on a slow-loading page the timeout could flip the flag even after the menu mounted fine, because nothing cancelled it. Both fixes shipped right after this release. Detection code needs the same skepticism as the code it watches.

The GitHub Action that reads HN every morning

The badge tells users something broke. It doesn't tell me, unless I happen to open HN that day. So the repo has a canary, .github/workflows/monitor.yml, and this is the whole thing:

name: HN Layout Monitor

on:
  schedule:
    - cron: '0 9 * * *'
  workflow_dispatch: {}

permissions:
  contents: read

jobs:
  check-layout:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run fixture:update
      - run: bun run test:integration

Every morning at 09:00 UTC it downloads the live HN homepage, overwrites the HTML fixture my integration tests run against, and runs the suite. If HN changed something my selectors care about, the suite fails, and GitHub's stock failed-workflow email lands in my inbox. No custom alerting, no dashboard. Nineteen lines of YAML watching a website on my behalf.

The integration tests assert more than "selectors match something." They pin the row counts, the elements inside each row, and even the formats of what's in them:

// app/utils/selectors.integration.test.ts (v2.6.1)
// Canary: validate HN's .age title attribute format ("ISO_DATETIME UNIX_TIMESTAMP")
const titleFormatRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2} \d+$/;
infoRows.forEach((row) => {
  const ageEl = getTimeElement(row);
  if (!ageEl) return;
  const title = ageEl.getAttribute('title');
  expect(title, 'age title should match "ISO UNIX" format').toMatch(titleFormatRegex);
});

// Canary: validate HN's .age text format ("X minute(s)/hour(s)/day(s) ago")
const ageTextRegex = /^\d+ (minute|hour|day)s? ago$/;
infoRows.forEach((row) => {
  const label = getTimeElement(row)?.textContent?.trim();
  if (label) expect(label, 'age text should match "N unit(s) ago"').toMatch(ageTextRegex);
});

If HN drops the Unix timestamp from the title attribute, time sort breaks and the first regex catches it. If "7 hours ago" ever becomes "7h", the second one fails before I've written a parser that cares.

A daily cron doesn't buy "before the first user notices." If HN ships a change at noon, users hit it all afternoon and my email arrives the next morning.

What the canary really buys is a bound: I find out in at most a day, instead of whenever I next happen to open HN with my own extension working. For a one-person project, turning "unbounded" into "24 hours" is most of the value.

And then the canary itself broke. In July 2026 the monitor started failing every day, and the cause wasn't HN's layout. The updater also refreshes a comment-page fixture (the comment features later in this post are tested the same way), and that fixture pinned a hardcoded item id.

HN had removed that thread, and their server answered every request for it with 429, forever. The watchdog needed watching.

The fix was to stop pinning data I could derive: the updater now picks the most-commented story off the fresh homepage each run, sends a browser User-Agent, and backs off politely when HN rate-limits. It's 75 lines if you want the fetch half of the pattern too. If your canary hardcodes anything about the site it watches, that's where it will rot.

If you maintain anything that scrapes or decorates someone else's site, steal this pattern. A cron workflow, a fixture refresh, and your existing tests.

One gotcha before you do: GitHub automatically disables scheduled workflows in a public repository after 60 days without repository activity. A canary guarding a project you consider finished is exactly the workflow that dies of that, so an occasional commit (or a calendar reminder to re-enable) is part of the deal.

And a risk I haven't paid yet: the canary fetches HN from GitHub's shared runner IPs, exactly the kind of traffic a site might one day rate-limit wholesale.

The timestamps HN rewrites

HN has a "second chance" pool: moderators and reviewers pick good stories that got no traction, and the site re-ups them onto the front page later. When that happens, HN rewrites the story's displayed age.

Not to the re-up moment, even: dang has explained it's back-computed, the time the story would have needed to be posted to deserve its new rank. A story submitted four days ago can honestly say "1 hour ago" on the front page.

It isn't rare, either, at least not on the day I checked. Here's a row from the snapshot of the front page I took while writing this (July 16, 2026):

<span class="age" title="2026-07-12T17:19:47 1783876787">
  <a href="item?id=48882777">1 hour ago</a>
</span>

The title attribute is the tell: HN rewrites the visible text, but the machine-readable timestamp keeps the original submission time, as an ISO datetime plus a Unix epoch. (Don't take the attribute's word for it: the official API's time field for that item returns the same 1783876787.)

You can count the rewrites on today's front page yourself. Paste this into DevTools on news.ycombinator.com:

const now = Date.now() / 1000;
const HOURS_PER_UNIT = { minute: 1 / 60, hour: 1, day: 24 };
const SLACK_HOURS = 2; // beyond truncation, allow a little drift before calling it a rewrite
let rewritten = 0;

for (const age of document.querySelectorAll('span.age')) {
  const epoch = Number(age.title.split(' ')[1]);
  const trueHours = (now - epoch) / 3600;
  const label = age.textContent.trim();

  const match = label.match(/^(\d+) (minute|hour|day)/);
  if (!match) continue;
  const [, count, unit] = match;
  // "3 days ago" is truncated: it covers anything from 72 up to (but not including) 96 hours.
  const labelCeiling = HOURS_PER_UNIT[unit] * (Number(count) + 1);

  if (trueHours - labelCeiling > SLACK_HOURS) {
    rewritten++;
    console.log(`"${label}" but submitted ${trueHours.toFixed(1)} hours ago`);
  }
}
console.log(`${rewritten} of ${document.querySelectorAll('span.age').length} ages look rewritten`);

Against my snapshot it printed (trimmed):

"1 hour ago" but submitted 88.4 hours ago
"9 hours ago" but submitted 116.7 hours ago
"5 hours ago" but submitted 116.0 hours ago
13 of 30 ages look rewritten

That's one snapshot on one day, so your count will differ. And the snippet detects rewritten labels, not who rewrote them: the second-chance pool is the best-documented mechanism, but moderator re-ups generally leave the same signature.

What survives is narrower: on any given day, a chunk of the HN front page may be days older than it says.

So the extension sorts by the field HN doesn't rewrite. The parser is small:

// app/utils/parsers.ts (v2.6.1)
const TITLE_UNIX_TS_INDEX = 1;

export const getTime = (infoRow: HTMLElement): number => {
  const timeElement = getTimeElement(infoRow);
  if (!timeElement) return 0;

  const title = timeElement.getAttribute('title');
  if (!title) return 0;

  const unixTs = parseInt(title.split(' ')[TITLE_UNIX_TS_INDEX]);
  return isNaN(unixTs) ? 0 : unixTs;
};

Once real timestamps were in memory anyway, showing them was nearly free. Since v2.5.0 the extension replaces the misleading label with the true age ("1 hour ago" becomes "3 days ago"), stashing HN's original text in a data-original-age attribute on the link.

Toggle the feature off and it restores the attribute and deletes it. No destructive edits.

Two confessions from the git history, since this section makes me sound more deliberate than I was.

The 2024 rewrite parsed the title attribute by throwing the whole thing at new Date(). That worked while the attribute was a bare ISO date, and Wayback Machine snapshots show it stayed bare until fall 2024.

Then HN changed the format twice in two months: fractional seconds and a Z by October 1, today's "ISO space epoch" by November 1. V8 parses the first happily and returns Invalid Date for the second.

So from around November 2024 until the fix shipped in late December 2025, sorting by time was quietly broken for every user of the extension. Nobody reported it. Not one review, not one issue, and I didn't notice either, for over a year: I sort by points myself, so the broken path wasn't one I walked. That is what silent failure looks like.

The second confession: an earlier version of this very post claimed the second-chance rewrite was corrupting my time sort before v2.5.0. It wasn't. The old code read the ISO half of the same attribute, which is just as original as the epoch half. The rewrite only ever lied to readers, through the visible text.

I caught my own false claim by re-checking it against the git history while writing. Verifying your war stories is part of maintenance too.

Sorts HN doesn't have: velocity and heat

Points, time, and comments are HN's own numbers, just sortable. Version 2.6.0 added two derived ones, and they exist because a different feature died.

I wanted to pin a thread's highest-scored comments to the top, until I checked the DOM and the API and found that HN hides comment scores from everyone except each comment's author. There is nothing to sort by. That dead end turned into: what can I compute from the numbers already on the page?

Two things, it turns out. Velocity is points per hour, damped:

// app/utils/sorters.ts (v2.6.1)
// Borrow HN's +2 gravity constant to keep young posts from spiking (not its full power-law rank).
const VELOCITY_DAMPING_HOURS = 2;

const velocity = (row: ParsedRow): number => {
  // Clamp age at 0 so a client clock running behind a post's server timestamp can't drive the
  // denominator to zero/negative (Infinity/NaN/negative rank); keeps the no-Infinity/NaN guarantee.
  const ageHours = Math.max(0, (nowInSeconds() - row.time) / SECONDS_PER_HOUR);
  return row.points / (ageHours + VELOCITY_DAMPING_HOURS);
};

Raw points-per-hour has a baby-post problem: a 20-minute-old story with a few upvotes beats everything on the page. Adding 2 hours to every denominator makes young posts earn their rank, and the penalty fades as posts age.

The + 2 isn't mine. In HN's own ranking code the denominator is (age in hours + 2) raised to a gravity power. I borrow the constant, not the exponent: velocity decays linearly where HN's rank decays as a power law, so this ranks momentum, not HN's front page.

And note which timestamp feeds it. row.time comes from getTime above, the epoch HN doesn't rewrite, so a second-chance story pretending to be an hour old doesn't get to pretend it's rising fast.

Heat is comments per point:

// app/utils/sorters.ts (v2.6.1)
const heat = (row: ParsedRow): number => (row.points === 0 ? HEAT_ZERO_POINTS_SENTINEL : row.comments / row.points);

A high ratio means a thread draws more comments than upvotes, which is sometimes exactly what you came for. (I'm not the first to notice this signal: hn-ratio has ranked HN's top stories by comment-to-score ratio for years; its author reads a high ratio as "active and extended debates.")

The sentinel is for job ads, which render with no score at all: -1 sinks them below every real story without the Infinity and NaN that naive division would spray into a comparator.

Both sorts get a toggle in the popup, and turning off the sort you're currently using reverts the page to HN's default order rather than silently switching you to points. Substituting a different metric without asking felt like the kind of thing I'd file a bug about.

Being a guest on someone else's page

Injection comes with etiquette problems on top of selector problems. The sort menu lives in HN's header, and HN's header has its own responsive behavior to not break.

The menu has three tiers (full words, single letters, a native dropdown), and the breakpoints are count-aware: React publishes how many sorts are enabled onto the panel root as a data-sort-count attribute, because the collapse thresholds are pure CSS and CSS can't read React state. The stylesheet keys its breakpoints on [data-sort-count='6'] and friends.

Each threshold sits just above the width where the menu would push HN's own nav links onto a second line. I measured those widths against HN's actual header, per option count, by resizing a window like a caveman. It was worth it.

The newest feature is on comment pages: the story author's comments get a subtle orange tint and an "OP" pill, and you can mark one other commenter per thread to highlight their replies. It exists because of a pattern HN regulars know well: someone else submits an article, and the actual author shows up in the comments saying "hi, I wrote this."

The mark is stored in sessionStorage, keyed by thread id. It survives reloads while you're reading and evaporates when the session ends, because a permanent cross-thread watchlist is a heavier thing than "follow this person through this discussion," and heavier wasn't the point.

Keyboard shortcuts get the same etiquette. Each sort has a hotkey (P, T, C, V, H, and D to restore HN's order), and on the first press of a key the handler checks whether another extension already claimed it. If event.defaultPrevented is true before I've done anything, something like Vimium got there first.

All sort hotkeys go inert, and the menu shows a note naming the exact keys that are taken.

Everything injected stays inside HN's palette (the orange is HN's own #ff6600), including the dot that marks posts new since your last visit, which fades out over a configurable cooldown and holds still if your system asks for reduced motion.

The settings popup follows your system's light or dark theme. The goal is furniture that looks like it was always there.

Stack, size, and the React question

TypeScript, React 19, and Plasmo, tested with Vitest against jsdom plus real-HTML fixtures, with Playwright generating the Web Store screenshots and demo GIFs. bun runs everything. About 1,600 lines of TypeScript and 540 of CSS, tests excluded.

No analytics, and the extension's own code makes no network calls (the manifest's only host permission is news.ycombinator.com). Settings ride chrome.storage.sync, which is Chrome's own sync infrastructure talking to Google's servers, not mine. MIT licensed.

Does sorting 30 table rows need React? No. The sort itself is querySelectorAll, a comparator, and re-appending rows in order.

React pays rent in the popup and the injected menu: settings that sync live across devices, toggles that enable and disable sorts, conditional banners. The DOM work that touches HN's table is plain DOM code in plain functions, which is also what makes it testable against a fixture that is literally yesterday's HN homepage.

Twelve years, one lesson

The extension has spent most of its life being finished. What kept it alive through the unfinished parts was never the feature code.

It was the boring perimeter: selectors anchored to names instead of positions, a sanity check before injecting, a flag in storage instead of a global, a red badge, a cron job reading HN at breakfast. None of that is HN-specific. Any code that depends on HTML it doesn't control is in the same war, whether it admits it or not.

Declare the dependency, even if only to yourself. Then build the perimeter around it.

Install: Hacker News Sorted on the Chrome Web Store
Source: github.com/svyatov/hacker_news_sorted

The four places a hand-rolled Ruby facade gives out

Leonid Svyatov — Thu, 16 Jul 2026 13:00:00 +0000

You don't need a gem to build a facade. This is a perfectly good one:

class App
  def self.config = Rails.configuration
  def self.redis  = REDIS_POOL
end

App.config reads better than Rails.configuration for the fortieth time, and App.redis beats remembering which global holds the pool. These are real methods. App.respond_to?(:redis) is true, the console tab-completes them, your editor jumps straight to the definition, and a wrong call raises ArgumentError at the call site. Your test suite can stub them with a verifying double (a stub that refuses to fake a method the real object doesn't have). If your App stays this size, close the tab. The class is the right tool, and reaching for a dependency to replace two lines would be silly.

I want to be honest about that up front, because I wrote a gem called briefly that builds this same object, and the interesting question isn't "isn't a facade nice." It's when does a hand-rolled one start to cost you, and whether the cost is worth a dependency. So here are the four places the plain class quietly gives out.

None of this is Rails-specific, by the way. briefly is a plain-Ruby facade; Rails is one optional pack it ships. I'll lean on Rails for examples because that's where most of us feel the pain, but the gem doesn't require it and the ideas don't either.

The plain class already beats the clever options

Before we compare a class to a gem, notice the class already beats the two "smarter" things you might reach for.

The first is method_missing. It's the reflex when you want App.anything to work without declaring it:

class App
  def self.method_missing(name, *) = REGISTRY.fetch(name) { super }
end

This works, and then quietly lies to everything that inspects it. App.respond_to?(:redis) is false, because there's no method there. Console completion shows nothing. Jump-to-definition lands nowhere. And in a test:

allow(App).to receive(:redis).and_return(fake)

RSpec's verifying doubles refuse. Their docs say it plainly: they "do not support methods which the class reports to not exist... This is commonly the case when method_missing is used." You can change what the class reports: pair method_missing with respond_to_missing? (the standard discipline; RuboCop has a cop that insists on it) and respond_to? flips to true, which satisfies verifying doubles too. What no pairing fixes is that there is still no method behind the name: nothing to tab-complete, nothing to jump to, no arity to check. A call working and a method existing are different things.

The other option is a dependency-injection container, like dry-rb's dry-container. It's a fine tool, but a different shape: you register objects under string keys and resolve them at runtime.

container.register("redis") { REDIS_POOL }
container["redis"]   # not container.redis

You look up "redis", a string, not redis, a method. That buys you container-agnostic wiring (dry-system will even auto-register components from file paths), and it costs you the jump-to-definition and tab-completion the plain class had for free.

So the spectrum looks like this, and the plain class is already sitting in the good spot:

	`method_missing`	plain class / facade	DI container
`respond_to?` sees it	with `respond_to_missing?`	yes	n/a (keyed)
console tab-completion	no	yes	no
jump-to-definition	no	yes	no
arity (argument count) checked	no	yes	past the lookup only
verifying doubles work	with `respond_to_missing?`	yes	stubs + injection instead

Two cells deserve their fine print. The container's lookup is a string key, which is what completion and jump-to-definition can't follow; the object it returns has perfectly real methods, and dry-container ships a test-stub mode besides, while constructor injection lets a spec hand in a verifying instance_double directly. And the method_missing column earns its two upgrades only when someone remembered to write respond_to_missing?.

Interestingly, Rails itself lands in the middle column. ActiveSupport::CurrentAttributes compiles real accessor methods with string codegen rather than reaching for method_missing.

Which means "briefly gives you real methods" is not a reason to use it. The class already has those. (briefly keeps them: its shortcuts sit in the same column, so everything in that table works on App exactly as on the plain class. One asterisk, and it's the plain class's win: shortcuts are compiled at runtime, so static analysis (Sorbet, Steep) can't see them the way it sees a hand-written def. briefly ships RBS signatures for its own API and a pattern for declaring your shortcuts' types, but on a strictly-typed codebase that's real friction the class doesn't have.) The reasons are elsewhere.

Tooth 1: memoization you can trust

Here is the first place the hand-rolled version can draw blood. You memoize something expensive:

def self.cache = @cache ||= build_cache

This is not a strawman. It's how Discourse does it, in a real 1,300-line Discourse module that is exactly the facade we're talking about:

def self.cache
  @cache ||=
    if GlobalSetting.skip_redis?
      ActiveSupport::Cache::MemoryStore.new
    else
      Cache.new
    end
end

@x ||= is the memoization idiom in every large app I looked at: Discourse, Mastodon, GitLab all reach for it. And it has two quiet bugs.

The first is threads. @cache ||= build is a check and then a set, and nothing makes those atomic: one thread can read @cache as nil and, before it assigns, another reads nil too, so both run build.

Whether that actually happens on MRI (the standard Ruby interpreter) comes down to one thing, and it isn't the one people usually reach for. MRI runs one thread at a time under its global VM lock, the GVL, but it preempts threads: the scheduler can pause one at a method call or a loop turn and let another run. A build that does I/O yields the moment it waits, and a pure-Ruby build gets paused too if it runs long enough to meet the timer. So the memo races when build is slow enough to be interrupted between the check and the set, and slips through clean only when it's short enough to finish in one time-slice.

I wrote the race out four ways, in three pieces that stack into one runnable file. First, the victim and the trigger: the classic idiom in a tiny facade, and a hammer that parks twenty-five threads on a Queue gate and releases them at once, so all of them hit the cold memo in the same instant:

require "briefly"

THREADS = 25

# The classic idiom. The check-then-set is not atomic across threads.
class RawFacade
  def initialize(&build) = @build = build
  def catalog = @catalog ||= @build.call
end

def hammer(obj)
  gate = Queue.new
  threads = Array.new(THREADS) do
    Thread.new do
      gate.pop      # park here until the gate opens
      obj.catalog
    end
  end
  THREADS.times { gate << :go }
  threads.each(&:join)
end

Next, the measurement. Each build bumps a counter so we can see how many times it really ran, and the counter takes its own Mutex: runs += 1 is itself a check-then-set, and a demo about a data race can't afford to undercount its own evidence with one:

def counting(&build)
  runs = 0
  lock = Mutex.new
  facade = RawFacade.new do
    result = build.call
    lock.synchronize { runs += 1 }
    result
  end
  hammer(facade)
  runs
end

Last, the contestants: three builds through the raw idiom, then the same I/O build through briefly's .memoize. The I/O build is a sleep standing in for a connect, sized wide enough that all twenty-five threads clear the nil check before any finishes, so it collides every time. That 25-of-25 is a forced maximum to make the shape unmissable, and the forced part is the gate (twenty-five arrivals in the same instant), not the sleep. (I also measured the unforced version: the same harness with a 2ms build and the arrivals scattered across 50ms re-ran the build one to three times across ten trials: a caller duplicates the build when it shows up while the first build is still running, and scattered arrivals rarely do.)

io_runs    = counting { sleep 0.02; Object.new }            # I/O: yields the GVL at once
short_runs = counting { (1..100).map { |i| i * 2 }.sum }    # short pure: one time-slice
long_runs  = counting do                                    # long pure: gets preempted
  n = 0
  40_000_000.times { n += 1 }
  n
end

brief_runs = 0
brief_lock = Mutex.new
app = Briefly.define do
  shortcut(:catalog) do
    sleep 0.02
    brief_lock.synchronize { brief_runs += 1 }
    Object.new
  end.memoize
end
hammer(app)

puts "raw `@x ||=`, I/O build (sleep):   #{io_runs} run(s) across #{THREADS} racing threads"
puts "raw `@x ||=`, short pure build:    #{short_runs} run(s) across #{THREADS} racing threads"
puts "raw `@x ||=`, long pure build:     #{long_runs} run(s) across #{THREADS} racing threads"
puts "briefly `.memoize`:                #{brief_runs} run(s) across #{THREADS} racing threads"

Stack the three pieces in one file with gem "briefly" and run it. It prints:

raw `@x ||=`, I/O build (sleep):   25 run(s) across 25 racing threads
raw `@x ||=`, short pure build:    1 run(s) across 25 racing threads
raw `@x ||=`, long pure build:     25 run(s) across 25 racing threads
briefly `.memoize`:                1 run(s) across 25 racing threads

The short pure build ran once; the long pure build, no I/O at all, still raced, because it ran long enough to be preempted (its body is a deliberately oversized loop, forced the same way the sleep is; what matters is that it races at all, not the count). So the line isn't I/O versus pure, it's fast versus slow.

Most of your memos are a fast computed value and are genuinely fine on MRI; this is no reason to distrust every @x ||= you've written. (Whether a real memo like Discourse's Cache.new above races comes down to the same line: does building it do the slow work up front, or defer it to first use? These apps also wrap the pools themselves in ConnectionPool, which is where their thread-safety actually lives.) And this whole picture is MRI's. JRuby and TruffleRuby run threads genuinely in parallel, no global lock narrowing the window, so the idiom has even less cover there.

The check-and-set was never atomic to begin with, which is why briefly's .memoize takes a real lock instead of trusting the runtime: the body runs once no matter how many threads race it or what it does. After that first write, reads hit a frozen snapshot and don't lock at all. The lock is one reentrant Monitor per facade, so a memoized body can read another memoized shortcut on the same facade without deadlocking itself. (The flip side of one lock per facade: two shortcuts on the same facade never build in parallel.)

App = Briefly.define do
  shortcut(:cache) { build_cache }.memoize
end

Threads share a memo by accident one way; fork is the other. A forking server (Puma in cluster mode with preload_app!, Unicorn) boots the app once and forks workers from it, so a connection memoized before the fork arrives in every worker already open (the classic shared-socket bug), and no memoization scheme can know a fork happened; briefly has no fork hooks. The fix is the usual one: don't call connection-holding shortcuts during boot, or clear the facade in the server's worker-boot hook with App.briefly.clear_memos!. (App.briefly is the management handle: briefly keeps every non-shortcut method behind that one accessor so your shortcut names stay free.)

The second bug is staleness. If you memoize something that holds a reloadable class, like ApplicationController.helpers, it goes stale the moment Rails reloads your code in development. You edit a helper, refresh, and nothing changes, because @helpers is pinned to the class from before the reload. briefly's Rails pack clears memos on every reload (and never in production, where nothing reloads), so the thing you cached is dropped exactly when it might have changed. The plain @x ||= has no idea a reload happened. (Where a value is cheap the pack doesn't memoize at all: its helpers and routes shortcuts are live lookups, re-read on every call, so there's nothing to go stale.)

briefly's memoization also refuses to do the wrong thing. Shortcuts take arguments fine (shortcut(:user) { |id| User.find(id) } is a real one-argument method, arity and all), but memoize one and it raises when you define the facade, not later:

Briefly.define { shortcut(:user) { |id| User.find(id) }.memoize }
# => Briefly::Error: cannot memoize user: its body takes arguments

because a value cached against nothing is all memoization can mean. And it caches nil and false correctly, which the bare ||= famously does not.

The test suite leans on the same two facts. Shortcuts are real methods, so allow(App).to receive(:cache) passes verifying doubles exactly as it would on the plain class. And memos are process-global state, so drop them between examples:

RSpec.configure do |config|
  config.after { App.briefly.clear_memos! }
end

Tooth 2: the first namespace you reach for

This is the one that made me stop hand-rolling. A flat bag of App.redis, App.cache, App.store is fine right up until you need your first namespace, and real apps need them fast.

Look at what a big app's grab-bag actually holds. Even Mastodon, the leanest of the ones I checked, has three separate Redis configs (base, sidekiq, cache). GitLab has more than a dozen. And GitLab doesn't keep them in a flat bag, it nests them into modules:

Gitlab::Redis::Cache.with { |r| ... }
Gitlab::Redis::Sessions.with { |r| ... }
Gitlab::Redis::SharedState.with { |r| ... }
# ~15 of these, each a subclass of a shared Wrapper

That's the natural end state. The bigger the app, the more it groups by subsystem rather than piling onto one object. Forem, the platform dev.to runs on, does the same with configuration: an ApplicationConfig facade over ENV plus a family of Settings::General, Settings::SMTP, Settings::RateLimit models, each its own little namespace. To be fair about what that evidence shows: these apps built their grouping by hand and maintain it fine: GitLab's Redis classes aren't grouped accessors, they're real classes carrying pooling and per-store config that no facade DSL would replace. The claim isn't that big apps fail without a gem. It's that grouping is where everyone ends up, and in a plain class every step of it is yours to build.

In a plain class, your first namespace means a nested module, or a second class, or prefixing method names by hand:

class App
  def self.redis = Redis          # the namespace is a nested module
  module Redis
    def self.cache    = CACHE_POOL
    def self.sessions = SESSIONS_POOL
  end
end

It works, but you're now maintaining that grouping by hand, and the day you want the memoization and reset-on-reload from Tooth 1 inside it, you're hand-rolling those again per module. briefly has namespace, and the child is a real facade you can pass around:

App = Briefly.define do
  namespace(:redis) do
    shortcut(:cache)    { CACHE_POOL }
    shortcut(:sessions) { SESSIONS_POOL }
  end
end

App.redis            # => a real Briefly::Facade, not a method_missing trick
App.redis.cache      # => CACHE_POOL

App.redis is a value, App.redis.cache is a real method on it, and the management claims are concrete APIs, not promises:

App.briefly.clear_memos!    # drops every memo, root and namespaces alike
App.briefly.configure do    # add or replace shortcuts on a live facade
  shortcut(:store) { NEW_STORE }
end

Clearing cascades through the whole tree. And a configure pass is atomic across every namespace: the new configuration is built off to the side and swapped in at the end, so a pass that raises anywhere leaves the whole thing exactly as it was. That's a chunk of correctness you'd otherwise be writing and testing yourself the day you split App.redis into App.redis.cache.

Tooth 3: packs, so you write it once

Real config repeats across apps. The redis, cache, logger, env block you set up in one service is the same block you set up in the next. In a plain class you copy-paste def self. across three repos and they drift.

A briefly pack is any object that responds to install. That's the whole protocol:

module RedisPack
  module_function
  def install(builder)
    builder.shortcut(:redis) { REDIS_POOL }
  end
end

Api = Briefly.define { use RedisPack }
Api.redis   # => REDIS_POOL

Two conveniences round the protocol out. You can register a short string name for a pack, and packs take options. Give install a keyword parameter and use forwards it:

Briefly.register("myapp/redis", RedisPack)    # once, e.g. in an initializer

Api = Briefly.define { use "myapp/redis", url: ENV["REDIS_URL"] }

(That version of RedisPack declares def install(builder, url:).) A pack isn't take-it-or-leave-it, either: declare a shortcut again after use and the last declaration wins, silently. That's the intended way to override one piece of a pack, and worth knowing before you shadow something by accident.

Nothing here touches Rails; it's a plain module. The Rails support you may have seen (use "rails", which gives you config, logger, env predicates, a db namespace, credentials, an error reporter, the live helpers/routes lookups from Tooth 1, and more) is just a pack shipped in the box, autoloaded only if you name it. You can write your own for your Stripe client, your feature flags, your search index, and share it.

That db namespace is the widest thing in the box, and it's the one I'd point at if you're deciding whether the Rails pack earns its keep. Aim it at one Active Record class and the multi-database surface comes back as shortcuts:

App = Briefly.define { use "rails" }   # `db` is a namespace it ships

App.db.txn { App.db.query("insert into audits (msg) values (?)", "hi") }
App.db.reading { App.db.select("select count(*) from events") }  # to the replica, if you run one

connection/conn lease a connection and release it at block exit; transaction/txn wrap a transaction; reading/writing pin the Rails role so reads land on a replica and writes on the primary; select runs a read through select_all, and query runs arbitrary SQL (writes and DDL included) through exec_query. One safety line: a statement with binds goes through sanitize_sql_array, a bindless string does not. The select/query split is about the query cache and intent, not a runtime read/write guard, so an interpolated string is still yours to get wrong.

And because a facade is cheap, you make several. One per area, each composing only the packs it needs:

Admin = Briefly.define do
  use "rails"
  shortcut(:audit_log) { AuditLog }
end

Worker = Briefly.define do
  use "rails/env"
  use "rails/reload"
end

Two independent facades, no shared state, each with its own memo cells and handlers. (Own locks, too, which cuts one boundary: two facades whose memoized bodies call each other can deadlock, like any pair of mutually-locking objects. Keep cross-facade calls out of memoized bodies.) You could share config another way, a module of def self. methods you extend into each app, and for a fixed handful of accessors that's fine. What a mixin doesn't give you is composition: packs stack (use several, pass each options), and every facade takes only the ones it needs, where an extended module hands every includer the same fixed surface.

Tooth 4: errors, aliases, and one honest footgun

A few smaller things you'd otherwise hand-roll.

Aliases that share one memo cell, so config and c are the same computed value, not two:

App = Briefly.define do
  shortcut(:config, :c) { expensive }.memoize
end

Scoped error handling, where the handler's return value becomes the shortcut's value:

App = Briefly.define do
  shortcut(:redis) { REDIS_POOL }.rescue_from(Redis::BaseError) { nil }
end

You can register a handler per shortcut, per facade, or globally, and they resolve most-specific first. (One syntax note for the standalone form: rescue_from StandardError { ... } binds the block to StandardError, not to rescue_from. That's Ruby's precedence, not briefly's. So write rescue_from(StandardError) { ... } or use do/end.) Which brings me to the sharpest edge, the kind of thing a facade invites you to get wrong. A facade-wide handler over StandardError catches your app's errors and also catches your own bugs:

App = Briefly.define do
  shortcut(:secret) { Rails.application.credentaisl.secret_key_base }  # typo: credentaisl
  rescue_from(StandardError) { nil }
end

App.secret   # => nil. No exception, no log, no clue.

At the moment the handler runs, a NoMethodError from a typo is indistinguishable from one the handler was written to absorb. A library can't read your intent from a backtrace, so briefly doesn't try. It documents the trap and points you at the narrow handlers that don't have it: scope the rescue to the shortcut that can actually fail, match the narrowest error class, and if you must go facade-wide, log and re-raise. I decided a sharp edge you can see beats a clever fix that's silently wrong a fraction of the time. That's a recurring theme in the gem, and it's worth more than any feature.

There's a second edge, subtler. Memoization doesn't compose with recovery. A rescue-backed shortcut that fails is careful not to cache its fallback: it retries next call and recovers. But if a memoized shortcut read it during that first, failing call, the reader has already baked the fallback into its own cached value, and pins it for the life of the process:

Briefly.define do
  shortcut(:flaky) { down? ? raise("down") : "up" }
    .rescue_from(RuntimeError) { "unknown" }
    .memoize
  shortcut(:summary) { "build #{flaky}" }.memoize
end
# first call, flaky is down  -> summary caches "build unknown"
# later, flaky recovers to "up" -> summary stays "build unknown", forever

The inner shortcut did the right thing and came back; the outer one had already committed. It's the same rule as .memoize holding nil and false: a fallback is a real value, and memoize's job is to keep the value it got. Worth a beat of thought before you .memoize something that reads a shortcut which can fail.

The gem underneath: candor

There's one thing briefly must not cost you compared to the plain class, and that's the honesty of its methods. A hand-written def self.config reports its real arity, its real parameters, and a source_location pointing at your code. If briefly's shortcuts were metaprogrammed stand-ins that reported (*args) and pointed into the gem, you'd have traded away exactly what made the class good.

Keeping that honesty turned out to be the hardest part of the whole project, and it lives in a second gem, candor, which briefly depends on and which has no dependencies of its own. It turns a block into a real method that reports the block's own signature:

mod = Module.new
Candor.define(mod, :greet) { |name, greeting: "hi"| "#{greeting}, #{name}" }

m = mod.instance_method(:greet)
m.parameters       # => [[:req, :__p0], [:key, :greeting]]
m.source_location  # => your block, not the gem

How it pulls that off is a story of its own. Ruby's reflection lies about blocks in more ways than you'd expect, and candor exists to un-lie each one. Even that :__p0 in the output, where a hand-written def greet(name, ...) would say :name, is a deliberate seam with a reason behind it. The seams, the trade-offs, and the parts of Ruby that fought back all get a follow-up post of their own. For this one, the takeaway is simple: briefly's shortcuts are real methods, and honesty is not part of the price.

So, when is it worth it?

If your App is five real methods, memoizes nothing that reloads, lives in one app, and never grew a namespace, keep the class. Same call if your team leans on Sorbet or Steep: a hand-written def is visible to the type checker, and a runtime-compiled shortcut isn't. You don't need a dependency for that, and I'd think less of the gem if it pretended you did. Even Rails' own CurrentAttributes, a facade blessed enough to ship in the framework, tells you in its docs not to overdo it: "only a few, top-level globals."

briefly earns its place at the first of these you hit: you memoize something expensive and want it correct under threads and reloads; you split one accessor into a namespace; you find yourself copying the same setup into a second app; or you add a rescue and want it scoped instead of swallowing everything. That's not day one. It's the day the drawer by the door stops closing, and you notice you've been maintaining the drawer.

gem "briefly"

Ruby 3.2 or newer, one dependency, Rails optional (the Rails pack wants Rails 7.2+). It's on GitHub and RubyGems under MIT. Write one less def self., but only once you'd have written the tenth.

The complete guide to `rails new` in Rails 8.1

Leonid Svyatov — Tue, 03 Mar 2026 10:23:12 +0000

rails new --help prints 30+ options. Most tutorials stop at rails new myapp -d postgresql and move on. This post covers every Rails 8.1 option - what it does, when to use it, and what most people pick.

App Mode

--api - Strips views, cookies, sessions, asset pipeline, Hotwire, CSS, and JavaScript. Use for pure JSON or GraphQL backends.

--minimal - Generates the smallest possible app. Skips Action Mailer, Action Mailbox, Action Text, Active Job, Active Storage, Action Cable, Hotwire, Jbuilder, tests, system tests, Kamal, Thruster, Solid, and Bootsnap. A good starting point when you want to add only what you need.

Database (`--database=X`)

Adapter	Pros	Cons	Best for
sqlite3 (default)	Zero setup, no server, works with Solid stack. 37signals runs ONCE products on it in production.	Single-writer, no multi-server scaling.	Solo devs, prototypes, single-server apps
postgresql ⭐	Full-featured (JSONB, arrays, full-text search), every PaaS supports it, best managed DB options.	Requires a running server.	Most production apps
mysql	Widely deployed, mature.	No native arrays, JSON can't be indexed directly (unlike PostgreSQL's JSONB).	Existing MySQL infrastructure
trilogy	Modern MySQL client by GitHub, no C library dependency, simpler install. GitHub & Shopify use it in production.	Newer, smaller ecosystem.	New MySQL projects
mariadb-mysql	For MariaDB specifically with mysql2 adapter.	Same as mysql.	Existing MariaDB setups
mariadb-trilogy	For MariaDB specifically with Trilogy adapter.	Same as trilogy.	New MariaDB projects

PostgreSQL is the most common choice. When in doubt, pick it.

--skip-active-record / -O - Drops the ORM entirely. Cascading effect: also skips database, Action Mailbox, Action Text, and Active Storage.

Frontend Stack

JavaScript (`--javascript=X` / `-j`)

Approach	Pros	Cons	Best for
importmap (default) ⭐	No Node.js, no build step, browser-native ES modules, HTTP/2 parallel downloads.	No tree-shaking, no TypeScript/JSX transpilation.	Standard Rails + Hotwire apps
esbuild	Extremely fast (Go-based), handles TypeScript/JSX, mature.	Requires Node.js.	Apps needing a bundler
bun	~1.75x faster than esbuild, doubles as package manager + bundler.	Newer, smaller ecosystem than esbuild.	Speed-first, Bun ecosystem
webpack	Full-featured, huge plugin ecosystem.	Slow, complex config, legacy choice.	Not recommended for new projects
rollup	Good for libraries, ES module focused.	Niche in Rails context.	Not recommended for new projects

Importmap is the Rails default for a reason - it eliminates Node.js from your stack entirely. Reach for esbuild or bun only when you need TypeScript, JSX, or tree-shaking.

--skip-javascript / -J - No JS setup at all.

CSS (`--css=X` / `-c`)

Framework	Pros	Cons	Best for
(none) (default)	No dependencies, write plain CSS.	No utilities or components.	Minimal apps, custom design systems
tailwind ⭐	Rails-blessed (`tailwindcss-rails` gem), no Node.js required, v4 is 5x faster with CSS-first config.	Verbose HTML classes, learning curve.	Most new Rails apps
bootstrap	Pre-built components, familiar to most devs.	Requires Node.js (via `cssbundling-rails`), heavier.	Apps needing ready-made UI components
bulma	CSS-only (no JS), clean modern design.	Requires Node.js via `cssbundling-rails`, smaller community.	Lightweight component needs
postcss	Plugin-based CSS transforms, flexible.	Requires Node.js, config overhead.	Custom CSS toolchains
sass	Variables, nesting, mixins, mature.	Requires Node.js (Propshaft doesn't compile Sass).	Teams already using Sass

No CSS framework is included by default. Tailwind is the most popular choice for new Rails apps - the tailwindcss-rails gem runs standalone, no Node.js required.

Asset Pipeline (`--asset-pipeline=X`)

Pipeline	Pros	Cons
propshaft (default) ⭐	Modern, lightweight - just fingerprinting and serving. Precompiles in seconds vs minutes.	No built-in preprocessing (delegates to external tools).
sprockets	Built-in Sass/CoffeeScript/ERB compilation, `//= require` directives.	Slow, complex, legacy.

Propshaft does one thing well: fingerprint and serve assets. If you need Sass or CoffeeScript compilation, Sprockets handles it - but you probably don't in 2025.

--skip-asset-pipeline / -A - No asset pipeline at all.

Hotwire (`--skip-hotwire`)

Turbo + Stimulus - the default Rails frontend framework. Turbo 8 introduced morphing (DOM diffing via idiomorph) that makes full-page refreshes feel SPA-smooth. Skip only if you're using a JS SPA framework (React, Vue) or building an API-only app (auto-skipped with --api).

The Solid Stack & Deployment

These are Rails 8 additions that replace external services with database-backed alternatives.

`--skip-solid`

Solid Cache + Solid Queue + Solid Cable - replaces Redis for caching, background jobs, and WebSockets. All database-backed, works with SQLite, PostgreSQL, and MySQL. 37signals runs 20M jobs/day on Solid Queue for HEY.

Solid Cache - database-backed caching. Higher latency than Redis RAM, but terabytes of SSD capacity at a fraction of the cost.
Solid Queue - uses FOR UPDATE SKIP LOCKED for efficient polling. Replaces Sidekiq/Resque for most apps.
Solid Cable - database-backed Action Cable. Polls every 100ms. Fine for moderate real-time needs.

Skip if: you already run Redis and need Sidekiq's advanced features (batches, rate limiting) or sub-millisecond cache latency.

`--skip-kamal`

Kamal 2 deploys Docker containers to any VPS (Hetzner, DigitalOcean, AWS EC2). Uses kamal-proxy (replaces Traefik) with automatic Let's Encrypt SSL. Zero-downtime deploys, rolling restarts.

Skip if: you deploy to a PaaS (Heroku, Render, Fly.io) or use Kubernetes.

`--skip-thruster`

Thruster - HTTP/2 proxy (written in Go by 37signals) that sits in front of Puma. Provides HTTP/2, gzip compression, asset caching, X-Sendfile, and automatic SSL. Replaces Nginx/Caddy for simple deployments.

Skip if: you already have a reverse proxy (Nginx, ALB, Cloudflare) or deploy to a PaaS.

Frameworks You Can Skip

Email & Rich Content

--skip-action-mailer / -M - No email sending or receiving infrastructure. Skip if your app never sends email.

--skip-action-mailbox - No inbound email routing to controller-like mailboxes. Requires Active Record. Skip if you don't process incoming email.

--skip-action-text - No Trix rich text editor integration. Requires Active Record. Auto-skipped in API mode.

Background & Storage

--skip-active-job - No background job framework. Also disables Solid Queue integration. Skip only if you handle no async work at all.

--skip-active-storage - No file uploads to S3/GCS/Azure. Requires Active Record. Skip if your app handles no file uploads.

--skip-action-cable / -C - No WebSocket framework. Also disables Solid Cable. Skip if you don't need real-time features.

JSON

--skip-jbuilder - Removes the Jbuilder JSON template DSL. Most API apps prefer render json: with serializers instead.

Testing & Code Quality

--skip-test / -T - Removes Minitest setup. Most people skip this to add RSpec instead.

--skip-system-test - Skips Capybara browser tests. Auto-skipped in API mode or when tests are skipped.

--skip-brakeman - Brakeman is a static security scanner for Rails that catches SQL injection, XSS, and 33+ other vulnerability types. Runs in seconds. Keep it.

--skip-bundler-audit - New in Rails 8.1. bundler-audit scans your Gemfile.lock for gems with known CVEs. Complements Brakeman: code scanning + dependency scanning. Keep it.

--skip-rubocop - RuboCop, Ruby linter, included by default since Rails 8. Keep it or swap in Standard Ruby.

--skip-ci - Skips the generated GitHub Actions workflow. Rails 8.1 CI includes Brakeman and Bundler Audit steps by default.

Infrastructure & Housekeeping

--skip-docker - Skips Dockerfile, .dockerignore, and bin/docker-entrypoint. Skip if you're not containerizing.

--devcontainer - Opt-in (not included by default). Generates VS Code dev container config with Redis, database, and Ruby all preconfigured.

--skip-bootsnap - Bootsnap caches expensive computations to speed up boot time. Rarely worth skipping.

--skip-dev-gems - Skips web-console and similar development gems.

--skip-keeps - Skips .keep files in empty directories. Git doesn't track empty dirs, so .keep files exist to preserve the directory structure.

--skip-decrypted-diffs - Skips git config for showing decrypted diffs of encrypted credentials.

--skip-git / -G - Skips git init, .gitignore, and .gitattributes.

--skip-bundle / -B - Skips bundle install after generation. Useful in CI or Docker builds where you control dependency installation separately.

Putting It Together - Common Recipes

Full-stack SaaS:

rails new myapp -d postgresql -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder

The workhorse setup. PostgreSQL, Tailwind, Solid stack, Kamal - all defaults. Skips Minitest (most teams add RSpec), Action Mailbox (few apps process incoming email), Action Text (add it later if you need a rich text editor), and Jbuilder (you'll use render json: or a serializer).

API backend:

rails new myapi --api -d postgresql -T \
  --skip-action-mailbox --skip-jbuilder

--api strips views, assets, cookies, and Hotwire. Skips Minitest for RSpec. Action Mailbox and Jbuilder rarely belong in an API.

Single-server indie app (the "one person framework"):

rails new myapp -d sqlite3 -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder

SQLite + Solid stack = no Redis, no PostgreSQL, no external services. Kamal and Thruster handle deployment and SSL. One server, one process, one database file. Add PostgreSQL later if you outgrow it.

PaaS deploy (Heroku, Render, Fly.io):

rails new myapp -d postgresql -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder \
  --skip-kamal --skip-thruster

Same as the SaaS setup but skips Kamal and Thruster - the PaaS handles containers, routing, and SSL for you.

Lean prototype:

rails new proto --minimal -d sqlite3

Bare minimum: no mailer, no jobs, no cable, no Hotwire, no Kamal. Add frameworks back as you need them.

If you don't want to memorize any of this, I built a tool for that. create-rails-app is an interactive CLI wizard that walks you through each option, remembers your choices, and saves reusable presets.

gem install create-rails-app

I got tired of looking up `rails new` flags, so I built a wizard for it

Leonid Svyatov — Fri, 27 Feb 2026 19:47:14 +0000

Every time I start a new Rails project, the same thing happens. I open the terminal, type rails new, and then... pause. What was the flag for PostgreSQL? Is it --skip-test or --skip-tests? Do I want Propshaft or Sprockets? What about Solid Queue — is that a flag now?

So I open rails new --help, scroll through a wall of options, and piece together a command I'll forget by next week.

After doing this too many times, I built create-rails-app — an interactive CLI wizard that walks you through every rails new option one at a time.

What it does

Instead of memorizing flags, you answer simple questions:

[01/31] API only application? (no)  ›  Yes / No
[03/31] Database (postgresql)       ›  sqlite3 / postgresql / mysql / trilogy ...
[04/31] JavaScript approach (importmap) › importmap / bun / esbuild / webpack ...

Each question shows your last-used choice as the default, so repeat projects take seconds.

At the end, you see the full rails new command — review it, then run it or go back and tweak your choices.

A few things I find useful

It remembers your choices. Next time you run it, your previous selections are pre-filled. Change one or two things and go.

Presets. Save a named configuration and reuse it:

create-rails-app myapp --preset api

I have presets for "api", "fullstack", and "minimal" — covers 90% of my projects.

Smart skip rules. Disable Active Record? It won't ask about databases. Choose API mode? It skips CSS and JavaScript framework questions. The wizard stays short and relevant.

Back navigation. Changed your mind three questions in? Ctrl+B goes back. No need to start over.

Version-aware. It detects your installed Rails version (supports 7.2, 8.0, and 8.1) and only shows options that apply.

Install

gem install create-rails-app

That's it. Run create-rails-app and follow the prompts.

Why not just use a template?

Rails templates are great for adding code after project creation. But they don't help with the rails new flags themselves — the database, JS bundler, asset pipeline, which frameworks to skip. That's the part I kept forgetting, and that's what this tool handles.

If you start new Rails projects more than once a year and find yourself googling the same flags, give it a try. Feedback and contributions welcome on GitHub.

clsx for Rails views

Leonid Svyatov — Sun, 03 Mar 2024 19:25:38 +0000

Hey, fellow Rubyists!

Have you ever found yourself wrestling with conditional class strings in your Rails views? Juggling string interpolation, conditional logic, and array manipulation to apply a class or two conditionally? It's like trying to thread a needle in a hurricane. Well, fret no more! Say hello to clsx-rails, the newest member of the Ruby gems family, here to make your life a tad bit easier.

Inspired by the simplicity of the clsx npm package, clsx-rails is your Rails view's new best friend. It's a tiny helper with a mighty purpose: to streamline how you handle CSS classes, making your code cleaner, more readable, and, let's be honest, more elegant.

Why `clsx-rails`?

Because we've all been there:

<div class="<%= ['foo', 'bar', condition ? 'baz' : nil].compact.join(' ') %>">
  Hello, Rails world!
</div>

It gets the job done, but it's about as graceful as a giraffe on ice skates. With clsx-rails, you can turn that mess into a one-liner marvel:

<div class="<%= clsx(:foo, :bar, baz: condition) %>">
  Hello, Rails world!
</div>

Usage Examples

Whether it's a string, a hash, or an array, clsx-rails handles them all, even nesting them like Russian dolls if that's your jam. It even eliminates any duplicates while at it! And for those who like their code like their coffee—short and strong - there's the cn alias.

# Variadic strings
cn('this', true && 'is', 'awesome')
# => 'this is awesome'

# Hashes with truthy/falsy values
cn(foo: true, bar: false, baz: condition)
# => 'foo baz' (assuming the condition is true)

Although not advised, it can handle any level of "complexity":

clsx(
  [[[['a'], 'b']]],
  { a: 1, b: 2 },
  [1, 2, 3, 4],
  { [1, 2, { %w[foo bar] => true }] => true }
)
# => 'a b 1 2 3 4 foo bar'

You can find more details and usage examples in the repo.

Why It's Useful

Keeps your views DRY and readable.
Reduces the mental overhead of handling conditional classes.
It's like giving your views a neat little toolbelt for CSS class manipulation.

So, if you're tired of the conditional class string chaos and want to add some syntactic sugar to your Rails views, give clsx-rails a whirl. Your views will thank you, and who knows, you might find yourself with a bit more time for coffee breaks :)

Happy coding!

How to hide Ruby 2.7 deprecation warnings system-wide

Leonid Svyatov — Fri, 24 Apr 2020 23:36:24 +0000

Are you using rbenv? Want to hide Ruby 2.7 deprecation warnings system-wide and not to deal with it on a per-project basis? This small tutorial is for you!

All you have to do is create file ~/.rbenv/rbenv.d/exec/hide-deprecations-for-2.7.bash with the following content:

# ~/.rbenv/rbenv.d/exec/hide-deprecations-for-2.7.bash

if [[ ${RBENV_VERSION%.*} == '2.7' ]]; then
  export RUBYOPT="-W:no-deprecated -W:no-experimental"
else
  unset RUBYOPT
fi

Done.

How exactly does it work can be found here.

I've tested it in Zsh. It should work in Bash, but I can't guarantee it.

Keep your Javascript dependencies under control

Leonid Svyatov — Mon, 04 Mar 2019 15:48:27 +0000

With all the Javascript libraries and their dependencies these days it’s easy to get carried away and lost track of how heavy your frontend is.

Here is a great tool for Webpack backed applications: Webpack Bundle Analyzer. It shows the exact size (parsed and gzipped included) of each dependency you put inside your package.json file.

And here is an example of how to add it to your Rails project.

First, we need to add it to the package.json:

# Save the package to your `devDependencies`
yarn add -D webpack-bundle-analyzer

Second, add this to your config/webpack/environment.js file, right before module.exports = environment; line:

if (process.env.ANALYZE_BUNDLE) {
  const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
  environment.plugins.append('BundleAnalyzer', new BundleAnalyzerPlugin());
}

Third, make it available as yarn/npm run task:

// package.json
{
  // ...
  "scripts": {
    // ...
    "analyze": "ANALYZE_BUNDLE=true RAILS_ENV=production ./bin/webpack"
  },
  // ...
}

Done. You can run it like this now:

yarn run analyze

Happy keeping your Javascript dependencies under control! :)

Easier usage of Rails 5.2 credentials and app-specific configuration

Leonid Svyatov — Sun, 24 Feb 2019 14:21:39 +0000

As you all know by now, Rails 5.2 introduced a new feature called Credentials. DHH said the following in the PR:

This new file is a flat format, not divided by environments like secrets.yml has been. Most of the time, these credentials are only relevant in production, and if someone does need to have some keys duplicated for different environments, it can be done by hand.

And as you should know by now, Rails 6.0 fixes this obvious inconvenience.

Meantime, a commonly proposed solution for Rails 5.2 was just to add environments by hands, something like so:

development:
  facebook_app_id: '...'
  facebook_app_secret: '...'
  facebook_app_namespace: '...'
  stripe_publishable_key: '...'
  stripe_secret_key: '...'
  stripe_signing_secret: '...'

production:
  facebook_app_id: '...'
  facebook_app_secret: '...'
  facebook_app_namespace: '...'
  stripe_publishable_key: '...'
  stripe_secret_key: '...'
  stripe_signing_secret: '...'

And then use it like this:

Rails.application.credentials[Rails.env.to_sym][:facebook_app_secret]

Pretty long and not very readable, right? Yeah, you probably don’t use credentials in that many places in your app anyway, but still. This line has 47 characters about Rails and just 22 characters about what you need. Not the best ratio, in my opinion.

The solution I’d like to show you is quite obvious, but I’ve never seen it being suggested anywhere (maybe I didn’t search right enough, sorry if that’s the case).

Just open config/application.rb and add credentials method like so:

require_relative 'boot'

require 'rails/all'

# Require the gems listed in Gemfile, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(*Rails.groups)

module YourApp
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 5.2

    # Settings in config/environments/* take precedence over those specified here.
    # Application configuration can go into files in config/initializers
    # -- all .rb files in that directory are automatically loaded after loading
    # the framework and any gems in your application.
  end

  def self.credentials
    @credentials ||= Rails.application.credentials[Rails.env.to_sym]
  end
end

Let’s see what it changes:

# Before:
Rails.application.credentials[Rails.env.to_sym][:facebook_app_secret]

# After
YourApp.credentials[:facebook_app_secret]

This approach abstracts Rails-specific details away, makes it concise, expressive and about your application. As a bonus it gives you a lot of flexibility: you can replace Rails credentials with something else, you can merge credentials from different places, you can easily upgrade to Rails 6 credentials by removing [Rails.env.to_sym] part, and so on.

OK, that’s great, but post’s title was also saying something about “app-specific configuration,” right? Correct! I want to show you one more thing that can make your life with Rails a little easier.

As your Rails application grows sooner or later, you will need a place to store various environment-specific details for your app: things that aren’t secrets or credentials, just some custom configuration. Rails documentation even has a section with this exact name: Custom configuration.

According to the documentation Rails offers us two pretty powerful options:

config.x namespace
config_for method

Neat! How about we use our credentials approach described above and combine with these two options?

Step 1: create config/app.yml

shared: &shared
  facebook_url: 'https://www.facebook.com/mysite'
  twitter_url: 'https://twitter.com/mysite'

development:
  <<: *shared
  domain: 'localhost:3000'
  devise_mailer_sender: 'no-reply@localhost'
  orders_mailer_sender: 'no-reply@localhost'

production:
  <<: *shared
  domain: 'mysite.com'
  devise_mailer_sender: 'no-reply@mysite.com'
  orders_mailer_sender: 'orders@mysite.com'

Step 2: fill in config.x from app.yml in the config/application.rb

# App specific configuration
config.x = config_for(:app).with_indifferent_access

Step 3: add config method to the config/application.rb file

  def self.config
    @config ||= Rails.configuration.x
  end

So your config/application.rb file now looks like this:

require_relative 'boot'

require 'rails/all'

# Require the gems listed in Gemfile, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(*Rails.groups)

module YourApp
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 5.2

    # Settings in config/environments/* take precedence over those specified here.
    # Application configuration can go into files in config/initializers
    # -- all .rb files in that directory are automatically loaded after loading
    # the framework and any gems in your application.

    # App-specific configuration
    config.x = config_for(:app).with_indifferent_access
  end

  def self.config
    @config ||= Rails.configuration.x
  end

  def self.credentials
    @credentials ||= Rails.application.credentials[Rails.env.to_sym]
  end
end

And we can use our custom configuration like so:

YourApp.config[:devise_mailer_sender]

How cool is that? :)

How to send Rails deprecation warnings to Airbrake

Leonid Svyatov — Mon, 18 Feb 2019 21:04:20 +0000

We’re upgrading our Ruby on Rails version from 4.2 to 5.2 this week. A long-awaited change for us. Of course, there are a lot of deprecation warnings that was thrown at us during this process. Rubocop and tests caught the vast majority of those, but we don’t have 100% code coverage, so some of these warnings got into production.

In development Rails send these warnings to the log file:

# Print deprecation notices to the Rails logger.
config.active_support.deprecation = :log

A reasonable default, but I changed it to :raise. It's way faster to find and deal with the warnings this way in development.

For production environment Rails uses ActiveSupport::Notifications:

# Send deprecation notices to registered listeners.
config.active_support.deprecation = :notify

The problem is that nobody listens for it in production. Fortunately, that was easy to fix with Airbrake. I tried to “google” the solution at first but didn’t find anything useful, so I’m sharing my solution for other seeking souls like me :)

# config/initializers/deprecations_notifier.rb

ActiveSupport::Notifications.subscribe('deprecation.rails') do |_name, _start, _finish, _id, payload|
  error = ActiveSupport::DeprecationException.new(payload[:message])
  error.set_backtrace(payload[:callstack].map(&:to_s))

  params = {
    gem_name: payload[:gem_name],
    deprecation_horizon: payload[:deprecation_horizon]
  }

  Airbrake.notify(error, params) do |notice|
    notice[:context][:severity] = 'warning'
  end
end

If you’re using CurrentAttributes and storing request.uuid there it would be a good idea to add current request UUID to the params as well.