DEV Community: Leonid Svyatov

Five ways to build a save panel, three of them correct

Leonid Svyatov — Fri, 07 Aug 2026 14:16:46 +0000

Here is a save panel: a spinner, an error banner, a dirty marker, a confirm dialog, and a closed flag. Five booleans, so thirty-two combinations. Have you ever written down all thirty-two?

I built it five times to find out what a statechart is actually worth. The first version breaks on the very first event I throw at it. The last version is the longest file of the five.

Every number I measured comes out of a script, and the command that printed it sits right above the output. The numbers I did not measure are linked instead. Versions: xstate@5.32.5, bun 1.3.14, TypeScript 7.0.2 and 5.9.3, 2026-08-06.

One scope note, because it cuts against the tool I am measuring. All five versions are pure functions from a state and an event to a new state: no view layer, no network, no request that actually goes anywhere. So XState's invoke never appears here, and neither does the cancellation that comes with it (which is a real part of what the library is for, and would have made one of the bugs below its problem rather than mine). I measure the shape of the state, and only that.

The spec, as eight rules

If the rules live in prose, every later claim is an opinion. So they live in code, once, and every implementation gets checked against the same eight. Each rule looks at one transition: the screen before, the screen after, the event, and whether the event was a reply to a save that is no longer running.

// R3: a reply from a save that is no longer in flight changes nothing.
R3_stale_reply_ignored: ({ stale, before, after, beforeInflight, afterInflight }) =>
  stale && (!sameView(before, after) || beforeInflight !== afterInflight)
    ? "a stale reply changed the screen"
    : null,

// R7: once closed, nothing changes.
R7_closed_is_terminal: ({ before, after }) =>
  before.closed && !sameView(before, after) ? "the screen changed after closing" : null,

// R8: a closed panel is not still saving, erroring, or asking.
R8_closing_stops_everything: ({ after }) =>
  after.closed && (after.spinner || after.errorBanner || after.confirmDialog)
    ? "the panel closed while still saving, showing an error, or asking"
    : null,

A rule returns a complaint or null, and sameView just compares the five on-screen signals. The other five rules cover the ordinary things: no spinner and error banner at once, a new save clears the old error, no second save while one is in flight, a successful save leaves the draft clean, and closing with unsaved edits asks first.

A walker drives all five versions. It starts at the initial state, fires every event, and repeats from everything new it finds. It also invents two kinds of server reply: one for the save the user is watching, and one for a save nobody is watching any more. That second one matters more than it sounds.

One: five booleans

This is the shape a panel starts as, and I wrote it as well as I could rather than as badly as I could. It already refuses a second save. It already clears the error banner when a new save starts.

function next(s: S, e: Ev): S {
  if (s.isClosed) return s;
  switch (e.type) {
    case "EDIT":
      return { ...s, isDirty: true };
    case "SAVE":
      if (s.isSaving) return s;
      return { ...s, isSaving: true, hasError: false };
    case "CANCEL":
      return { ...s, isSaving: false };
    case "SAVE_OK":
      return { ...s, isSaving: false, hasError: false, isDirty: false };
    case "SAVE_ERR":
      return { ...s, isSaving: false, hasError: true };
    case "CLOSE":
      if (s.isDirty) return { ...s, isConfirming: true };
      return { ...s, isClosed: true };
    case "CONFIRM_DISCARD":
      return { ...s, isConfirming: false, isClosed: true };
    case "KEEP_EDITING":
      return { ...s, isConfirming: false };
  }
}

It breaks R3 on the first event the walker tries.

A SAVE_ERR arrives belonging to a save that is not running (the user cancelled, say, and the request landed anyway). The panel shows an error for something nobody is waiting on.

Look at the code and you cannot fix it. case "SAVE_ERR" has nothing to compare against. Five booleans can say a save is happening. They cannot say which one.

That is the point where flags start disagreeing with each other, and it is not the tired isLoading && isError complaint. The mainstream answer to that one has been an enum since 2020, when Kent C. Dodds wrote Stop using isLoading booleans. Your reader already agrees. This is a different failure: the flags are individually correct and collectively meaningless.

Two: name the request

So a reviewer says: give the request a number. Fine.

case "SAVE":
  if (s.isSaving) return s;
  return { ...s, isSaving: true, hasError: false, saveToken: s.nextToken, nextToken: s.nextToken + 1 };
case "SAVE_ERR":
  if (e.token !== s.saveToken) return s;
  return { ...s, isSaving: false, hasError: true, saveToken: null };

R3 is fixed. R8 still breaks.

SAVE, then CLOSE on a clean draft. The panel closes with saveToken still set and isSaving still true. The screen is gone, and the model thinks a save is in flight behind it.

The moment you add a token you have stopped using flags and started storing state. The last three versions are all arguments about what shape that state should take.

Three: a union for the save

Here is the version the skeptic asks for, and the skeptic is not a strawman. Here is one, in 2023: "I think this is solved more generally with a discriminated union in typescript. A state machine is the wrong solution unless you also need to restrict transitions themselves."

type Save = { tag: "idle" } | { tag: "saving"; token: number } | { tag: "error" };

type S = {
  save: Save;
  dirty: boolean;
  confirming: boolean;
  closed: boolean;
  nextToken: number;
};

The token now lives inside saving and nowhere else. You cannot read a token off an idle save, because there is nothing to read.

It passes all eight rules.

That is worth sitting with, because it is the honest answer to the question everyone asks first. A tagged union and a switch solve this feature. No library, twenty-four lines of transition logic, done.

It also answers a question I found asked in April 2026 in an eighty-six comment thread, with no reply: since the state chart itself doesn't contain any data, where does the data live, and how do you handle data that's only valid in certain states?

The union's answer is the good one. Data hangs off the state that owns it, so the compiler stops you reading it anywhere else:

type State =
  | { tag: "guest" }
  | { tag: "member"; user: string };

export function greet(s: State): string {
  // `user` exists on exactly one member of the union, and this reads it from the whole union.
  return s.user;
}

error TS2339: Property 'user' does not exist on type 'State'.
  Property 'user' does not exist on type '{ tag: "guest"; }'.

XState has no equivalent. Its context is one object typed once for the whole machine, so a field that only makes sense in one state is typed as present in all of them:

PASS  context.user is reachable, and null, while the machine is in `guest`
      guest context.user = null (the type says string | null in EVERY state)

The union asks the compiler a question the machine cannot be asked. That is a real thing it wins, and none of the articles I read concede it.

So why keep going?

Because the union's clean sheet is held up by two lines somebody has to remember to write:

const close = (s: S): S => ({
  ...s,
  closed: true,
  confirming: false,
  ...(opts.closeResetsSave ? { save: { tag: "idle" as const } } : null),   // line one
});

function next(s: S, e: Ev): S {
  if (opts.closedGuard && s.closed) return s;                              // line two

I made both switchable so the run can price them:

bun run src/verify-three-ways.ts

variant                                                 rules broken  which
union reducer  closedGuard=true closeResetsSave=true    0             none
union reducer  closedGuard=true closeResetsSave=false   1             R8
union reducer  closedGuard=false closeResetsSave=true   2             R7,R8
union reducer  closedGuard=false closeResetsSave=false  2             R8,R7

One line says once closed, ignore everything. The other says closing also stops the save. Neither is enforced by the shape. They are vigilance, written down.

And the shape allows twenty-four of the thirty-two screens while the code only ever reaches fourteen. Ten configurations exist that nothing produces and nothing checks. closed: true next to save: { tag: "saving" } is one of them.

Four: a state machine, by hand

A state machine is three things: a set of states, a set of events, and a table saying which event moves you from where to where. That is the whole idea. It predates all of this and needs no library.

Written out, the states cover every combination of what the save is doing and whether the dialog is up. Here is one row of that table, for the state where a save is running and the dialog is down:

savingHidden: {
  EDIT: { to: "savingHidden", then: dirty },
  CANCEL: { to: "idleHidden", then: clear },
  SAVE_OK: { to: "idleHidden", when: isFresh, then: saved },
  SAVE_ERR: { to: "errorHidden", when: isFresh, then: clear },
  CLOSE: [{ to: "savingConfirming", when: isDirty }, { to: "closed", when: notDirty, then: clear }],
},

Three keys, and I picked the names: to is the next state, when is a guard that has to hold, and then updates the data alongside the state. A list is tried in order, so CLOSE asks the dialog first and closes only if the draft is clean. The helper named clear is the one worth reading twice: it does not clear the error, it forgets the token of the save in flight.

Seven states, twenty-eight arrows, no dependency. It breaks nothing, and it reaches exactly the same fourteen screens as everything that follows.

Note what fixed R8 here, because it is easy to credit the wrong thing. closed became a state instead of a field sitting beside the save. A state cannot be occupied at the same time as savingHidden, so "closed while saving" stopped being expressible. That is states beating flags. It has nothing to do with statecharts yet.

So, do you need the library? At this size: no. GitLab reached the same conclusion and wrote about a hundred lines of finite state machine into their own utils folder in 2021, where it still sits with no hierarchy and no regions. Expo went further: they keep an XState model of their update logic in TypeScript as a reference document and ship the real thing hand-written in Kotlin and Swift.

Look again at that table, though. EDIT appears in every single row. savingConfirming exists only because saving and confirming can happen together. Both of those are the smell.

The two ideas

David Harel worked the two ideas out over 1982 and 1983, and he says what they are in one sentence:

Besides a host of other constructs, the two main ideas in statecharts are hierarchy and orthogonality, and these can be intermixed on all levels.

Think about the light switches in a house.

Hierarchy is the breaker. The kitchen has its own switch, and so does the porch, but there is one breaker upstream of both, and throwing it turns off every room at once. Nobody wires "and also go dark when the breaker trips" into each individual lamp. That is a state containing states: being in open means being in exactly one of its children, and anything true of open is true of all of them. It is XOR, and it is why EDIT is written once on the parent instead of six times on the leaves.

Orthogonality is the two switches. The kitchen light does not know or care whether the porch light is on. You could label all four combinations on a single dial (kitchen-on-porch-off, kitchen-off-porch-on, and so on) and it would work, and you would relabel the whole dial the day somebody adds a hallway. Or you keep two switches. That is what the panel's save and its dialog are: one list of seven names becomes two lists of three and two. It is AND, and it is why savingConfirming stops needing a name.

The four combinations still exist in the house. You just stopped writing them down.

Harel is careful about what orthogonality is not, and every tutorial I read got this wrong:

Orthogonal state-components in statecharts are not the same as concurrent or parallel components of the system being specified ... but simply to help structure its state space.

So: not threads, and nothing runs at the same time. Two switches on one wall.

Here is the panel with both ideas applied:

draft
│
├── open              two regions, both live at once
│   │                 on EDIT: mark dirty   <- written once, works from every leaf below
│   │
│   ├── save                          ├── dialog
│   │     idle                        │     hidden
│   │       SAVE          -> saving   │       CLOSE [dirty] -> confirming
│   │     saving                      │       CLOSE [clean] -> closed
│   │       SAVE_OK [fresh] -> idle   │     confirming
│   │       SAVE_ERR [fresh] -> error │       KEEP_EDITING    -> hidden
│   │       CANCEL        -> idle     │       CONFIRM_DISCARD -> closed
│   │     error                       │
│   │       SAVE          -> saving   │
│
└── closed (final)     leaving `open` exits BOTH regions

Five: the statechart

Same spec, same eight rules. The guards and actions get declared first, then the shape.

export const machine = setup({
  types: {} as { context: Ctx; events: Ev },
  guards: {
    isDirty: ({ context }) => context.dirty,
    isFresh: ({ context, event }) =>
      (event.type === "SAVE_OK" || event.type === "SAVE_ERR") && event.token === context.token,
  },
  actions: {
    startSave: assign({
      token: ({ context }) => context.nextToken,
      nextToken: ({ context }) => context.nextToken + 1,
    }),
    forgetSave: assign({ token: null }),
    markSaved: assign({ dirty: false, token: null }),
    markDirty: assign({ dirty: true }),
  },

isFresh is the same token check from version two, named once and reused by both replies.

Then the shape. open is the parent, type: "parallel" makes its children regions rather than alternatives, and EDIT sits on the parent:

}).createMachine({
  id: "draft",
  context: { dirty: false, token: null, nextToken: 0 },
  initial: "open",
  states: {
    open: {
      type: "parallel",
      // Hierarchy: EDIT is written once here and covers every leaf below it.
      on: { EDIT: { actions: "markDirty" } },
      states: {
        // Orthogonality: these two regions are both live and neither knows about the other.
        save: {
          initial: "idle",
          states: {
            idle: { on: { SAVE: { target: "saving", actions: "startSave" } } },
            saving: {
              on: {
                SAVE_OK: { guard: "isFresh", target: "idle", actions: "markSaved" },
                SAVE_ERR: { guard: "isFresh", target: "error", actions: "forgetSave" },
                CANCEL: { target: "idle", actions: "forgetSave" },
                // No handler for SAVE: a second save cannot start while one is in flight.
              },
            },
            error: { on: { SAVE: { target: "saving", actions: "startSave" } } },
          },
        },

Read the saving block again. The rule against a second save while one is in flight is expressed by leaving something out.

The dialog region never mentions the save. Two things in it need a word. #draft.closed is an absolute target: the # means "start from the machine's id", which you need here because closed is not a sibling of hidden. And a list of transitions is tried in order, so the guarded entry gets first refusal and the unguarded one is the fallback:

        dialog: {
          initial: "hidden",
          states: {
            hidden: {
              on: { CLOSE: [{ guard: "isDirty", target: "confirming" }, { target: "#draft.closed" }] },
            },
            confirming: {
              on: { KEEP_EDITING: { target: "hidden" }, CONFIRM_DISCARD: { target: "#draft.closed" } },
            },
          },
        },
      },
    },
    // Leaving `open` exits both regions. Nothing has to remember to stop the save.
    closed: { type: "final" },
  },
});

closed is a sibling of open, one level up. The save region is never asked to stop. It stops because it no longer exists. (That is the breaker again: nothing tells the kitchen light to go off.)

That is the union reducer's closeResetsSave line, deleted and replaced by a shape.

Now run all five:

bun run src/verify-three-ways.ts

SPEC: a draft editor's save panel. 8 rules, 8 events, 5 on-screen signals (2^5 = 32 screens).

implementation                  screens allowed  screens reached  never checked  rules broken
booleans                        32 of 32         21               11             R3,R8
booleans + request token        32 of 32         21               11             R8
union reducer                   24 of 32         14               10             none
flat machine, no library        14 of 32         14               0              none
statechart (XState v5)          14 of 32         14               0              none

On this spec the statechart wins nothing on correctness. The union reducer catches every rule it catches, and so does a flat machine with no dependency at all. All three reach an identical set of fourteen screens, and the run fails on purpose if they ever diverge.

Do not read too much into the "screens allowed" column, though. It flatters machines by construction (a machine's set of possible states is its list of declared states, so its slack is structurally zero), which means it separates machines from flags and tells you nothing about statecharts against flat machines.

And the walker is a search, not a proof: it treats two internal states that look identical on screen as one node. So a second check expands every path to a fixed depth, with no de-duplication at all:

bun run src/probe-exhaustive.ts

The shipped walker de-dups by (screen, save in flight?). This one does not de-dup at all:
every event path to depth 6, on all three implementations that broke no rule.

  union reducer              paths= 352971  violations=none
  flat machine, no library   paths= 374841  violations=none
  statechart (XState v5)     paths= 374841  violations=none

PASS: the de-duplicating walker hid nothing. Same verdict under the exhaustive one.

Six events deep is a bound, not a proof. It is a much wider net than the first walk, and it is still a net.

So what did that buy?

Arrows.

bun run src/verify-explosion.ts

Same spec, same behaviour, two shapes:

  flat machine     7 states, 28 arrows written by hand
  statechart       6 leaf states (10 nodes with parents), 10 arrows written
  ratio            2.8x fewer arrows in the statechart

I do not want you to take that on faith, and I did not either. The script flattens the statechart mechanically: cross-product the two regions, copy each leaf's arrows into every combination it appears in, add the parent's arrows once per combination. It gets seven states and twenty-eight arrows. That is the hand-written flat machine, exactly, and the script exits non-zero if it ever stops matching.

Which means I can add concerns and let it do the arithmetic. Each new concern below is a two-state toggle with one arrow per state. An "offline / online" indicator. A "compact / expanded" view.

  extra   flat states   flat arrows   chart leaves   chart arrows   union: allowed / unchecked
  0       7             28            6              10             24 / 10
  1       13            68            8              12             48 / 20
  2       25            160           10             14             96 / 40
  3       49            368           12             16             192 / 80
  4       97            832           14             18             384 / 160

Four independent toggles is not an exotic feature (a save panel that also knows about the network, the layout, whether the document is shared, and whether you are on a phone). Ninety-seven states and eight hundred arrows, or fourteen states and eighteen arrows.

But read the last column before you conclude anything, because the union reducer is not on the exploding side of this table. A toggle costs it one more boolean field, not a cross product of names. What grows for the union is the space nothing checks: at four toggles its shape admits 384 configurations, 160 of which nothing reaches and no rule inspects. The statechart's figure there is zero at every row, because a machine's shape is its list of states.

So the choice the table actually offers is not statechart or explosion. It is: write the cross product out by hand, or keep a boolean field per concern and accept that most of what your type allows is never looked at.

And here is the caveat that keeps the rest of it honest: both machine columns describe the same program. The configuration space did not shrink. Three regions of two states each is eight configurations either way:

bun run src/verify-orthogonality.ts

Three orthogonal regions, two states each:

  written down     6 leaf states, 6 arrows
  reachable        8 configurations
  the formalism    2^3 = 8
  initial value    {"a":"a1","b":"b1","c":"c1"}

Orthogonality does not make your program simpler. It makes the description shorter, and the description is the thing a person has to hold in their head.

One more thing before I let the statechart off. Back in section three I knocked out the reducer's two hand-written lines to show they were vigilance rather than structure. It would be unfair to stop there, so I ran the same sweep on the statechart:

statechart     isFresh=true                             0             none
statechart     isFresh=false                            1             R3

Turn off the token guard and the statechart breaks R3, exactly the way the flags version did on the very first event. Neither the hierarchy nor the two regions produce that guard. It is a line I wrote by hand, same as the reducer's two, and nothing complains when it goes missing.

So the score is honest: the shape bought R7 and R8, in every version that made closed a state. It did not buy R3, in any version. Somebody has to write that one down.

That is the whole trade. A statechart is a notation.

Harel ranked state explosion second

Which is exactly what it was built to be, and the story is not the one usually told.

In December 1982 Harel took a consulting job: one day a week, Thursdays, at Israel Aircraft Industries, on the avionics team of the Lavi fighter. He describes it himself in a 2007 account that he labels highly personal and subjective, so read it as testimony rather than measurement.

The specification was two volumes of structured English, around a thousand pages each. He asked what he thought was a simple question: what happens when you press this button on the stick?

They answered it. They opened volume B, found the clause, and read it to him. So he added a condition, and they found a different clause in the other volume.

Q1   what happens when you press this button?        volume B, clause 19.11.6.10
Q2   ... even with an infra-red missile locked on a ground target?  volume A, clause 6.12.3.7
Q5   ...                                             the engineers phone the customer
Q8   ...                                             "even those people often did not have an answer"

"Those people" is the Air Force team that owned the requirements. The team knew exactly what algorithm the radar used to measure distance to a target, and could not say what happens when you press this button under all possible circumstances.

Now the part everyone gets backwards. Ask why statecharts exist and you will be told: state explosion. Harel puts that second.

not only because of the number of states ... even more important seemed to be the pragmatic point of view

The more important half, in his words, is that a flat list of states "has no means for modularity, hiding of information, clustering, and separation of concerns". He was complaining that you could not organize the states, not that there were too many of them.

That is a notation problem described in the vocabulary of software design, and it is why the growth table above is the second reason to care rather than the first.

The diagrams came last, and by accident. Harel first wrote a textual language, hierarchical "statocols" (structured state protocols, and the name did not survive either), and doodled pictures beside it to explain it. The engineers understood the doodles better than the language. Within weeks he was asking whether the pictures could replace the text rather than illustrate it.

The paper was rejected for about two and a half years. One referee wrote that "the topic is good only for a very narrow audience". Crossref counted 4,392 citations of it on the day I looked.

And the idea travelled a long way past the fighter jet. SCXML became a W3C Recommendation in September 2015, with a normative interpretation algorithm and a conformance section, explicitly "based on CCXML and Harel State Tables". Qt ships an engine for it that generates C++. Do not read that as portability for the code in this post, though: XState says it is "inspired by" SCXML and claims no conformance, so a machine written here does not move to another engine. UML state machines are, in the OMG's lineage, an object-based variant of Harel's statechart. NASA JPL generated flight code from them for the Space Interferometer Mission, and Deep Space 1 was their first mission to do it, though the public JPL autocoder repository is a ground tool whose header reads "(NO FLIGHT CODE ALLOWED)".

One tool that sells the notation, meanwhile, refuses the word. MathWorks Stateflow generates C, C++, VHDL and Verilog, and its customer stories name surgical device control and antenna stabilization. Its product page never once says "Harel" or "statechart". It says state transition diagrams and truth tables.

Splitting a machine, and the types

Everything above is one small machine. The complaint I kept running into starts with the second one: people try to split a definition into reusable pieces and the types fight back.

That complaint dates from XState v4, so I re-ran it against what ships today, on both current TypeScript majors:

bun run src/verify-ts-splitting.ts

xstate 5.32.5, tsc --strict, TypeScript 7.0.2 and 5.9.3

                                                            7.0.2           5.9.3
A  shared sub-state object, spread into two machines        FAILS TS2345    FAILS TS2345
A2 the same chunk, with `as const`                          FAILS TS2345    FAILS TS2345
A3 the same chunk, typed from the builder's config type     compiles        compiles
B  split into a child machine and invoked                   compiles        compiles
C  persist a snapshot and restore it, no `any`              compiles        compiles
D  config chunk in another module, guard named in setup()   FAILS TS2345    FAILS TS2345
D2 the same chunk, with `as const`                          compiles        compiles
D3 the same chunk, typed from the builder's config type     compiles        compiles
E  the documented way: setup(...).createStateConfig(...)    compiles        compiles

Both compilers agree on every case.

The naive split does still fail. Plain TypeScript causes it, though, not statecharts: pull a chunk into a bare object literal and "isHigh" widens from a literal to string, and the config type wanted the literal.

The fix is documented and I had missed it. setup(...).createStateConfig(...) has shipped since 5.21.0 and it compiles clean with the guard still named as a string, no cast:

const builder = setup({
  types: {} as { context: Ctx; events: Ev },
  guards: { isHigh: ({ context }) => context.count > 3 },
});

export const states = builder.createStateConfig({
  initial: "low",
  states: {
    low: { on: { BUMP: [{ guard: "isHigh", target: "high" }, { target: "low" }] } },
    high: {},
  },
});

Do not reach for as const instead. It rescues case D2 and stops working the moment the chunk contains an inline assign(...), which is case A2, still failing above.

Harel, incidentally, would not have started here at all. "No one is encouraged to specify a single statechart for an entire system," he writes, footnoting that his own famous digital-watch example did exactly that for presentation reasons.

The bill

The statechart is the longest of the five files:

bun run src/verify-cost.ts

lines of code, blank and comment lines dropped:

                       whole file   transition logic only
  booleans             62           23
  booleans + token     68           25
  union reducer        70           24
  flat machine         94           40
  statechart           116          57
  (whole-file counts include the adapter each version needs to join the test harness)

Read the right column (the left one counts each version's glue into my test harness, which is my problem and not yours). Fifty-seven lines of transition logic against the union reducer's twenty-four, for identical behaviour. That gap is real, and I did not measure where or whether it closes, so I will not tell you that it does.

Then the bytes. And here I got a surprise, because I assumed the weight was the runtime:

bun run src/verify-cost.ts   # same script, second half of its output

  nothing (baseline)   min     24 B   gzip    44 B   (esbuild    44 B)
  xstate               min  42362 B   gzip 13965 B   (esbuild 12697 B)
    the builder only   min  42333 B   gzip 13947 B   (esbuild 12688 B)
    the runtime only   min   9937 B   gzip  3452 B   (esbuild  3088 B)
    pure transitions   min  10379 B   gzip  3586 B   (esbuild  3225 B)
  @xstate/store        min   7330 B   gzip  2854 B   (esbuild  2789 B)

  the two bundlers differ by at most 11% on any real row.

The thing that drives a machine is three and a half kilobytes. The thing that defines one is fourteen. Of the 13,965 bytes you actually ship, the runtime is 3,452, so three quarters of it is the notation. (Do not add the builder and the runtime together: they overlap heavily, so the two numbers are not a split of the total. And never quote a kilobyte figure without saying which bundler produced it, which is what that eleven percent is doing there.)

While measuring that, I noticed @xstate/store advertises itself as "Extremely small: less than 1kb minified/gzipped". Today it measures 2,854 bytes gzipped. I installed version 1.0.0 to check, and there the claim was true: 533 bytes. The package grew and the line did not.

More costs, none of which the field prices:

What you learn expires. XState has shipped three incompatible ways to write a machine in three majors.

2018-10-29  v4         Machine(...)         cond:     interpret(...)
2023-12-01  v5         createMachine(...)   guard:    createActor(...)   setup({ types })
2026-06-20  v6 alpha   the v5 action and guard creators removed; schemas replace types

The v4-to-v5 migration guide runs 2,237 lines with 47 breaking changes, and some change meaning rather than spelling: transitions became internal by default, and child state nodes are always re-entered. A chart drawn against v4 behaves differently under v5.

Then v6 alpha arrived in June 2026 and deleted the vocabulary I used above: assign, raise, sendTo, enqueueActions, and the and, or and not guards. That is why every snippet here is stamped 5.32.5, and why you should check the date on any XState article before you copy from it, this one included.

Learning it is the cost everyone names first. I cannot measure this and neither can anyone else, so here it is as testimony: one practitioner puts the curve "more similar to rx-js or fp-ts than a state manager", another says "building state machines is an art in and of itself and I had to throw away my first implementation". Take those as reports rather than as a number, but notice that three of the four introductions I read name the learning curve as the top cost and then move on.

The diagram costs money, or is abandoned. The payoff people rate highest is showing the chart to someone who does not read code. The old visualizer repository is archived and its README now reads "XState (Legacy) Visualizer". The VS Code extension was last updated in January 2024 and the docs still say it is not compatible with v5, which shipped in December 2023. The current editor is a product: free if your projects are public, $33 a month billed annually or $39 monthly if they are not.

The other advertised payoff is also between homes. Generating test paths from the machine is one of the benefits the introductions I read put near the top. I hand-rolled the exhaustive walker above; XState ships that idea too, and its documentation page currently says the utilities have moved into @xstate/graph and that the docs for them are "coming soon", while what is written is for a beta of the package they replaced.

That payoff is also contested. A former gadget.dev engineer, in the same 2026 thread, reports the opposite result: "we started with hierarchical statecharts as a way for users to specify their behaviour ... No matter what we did, users just found it incredibly confusing." He also reduced "1000+ lines of very hard to read and extend statechart code to a few hundred lines of imperative code" and found that easier than fixing the bugs hiding in it. He is not an opponent ("I love the idea of statecharts, I just have scars from dealing with them"). One person's experience, self-reported, and worth more than a benefits page.

Some things it will not catch. Send an event the current state does not handle and XState swallows it: the actor stays where it was, says nothing, and carries on. A typo in a target does throw, early, at createMachine time before any actor exists, which beats a hand-rolled switch where a mistyped string waits until runtime. But TypeScript will not catch that typo. And this machine constructs without complaint and then never finishes starting:

createMachine({ initial: "a", states: { a: { always: "b" }, b: { always: "a" } } });

The docs say XState "will help guard against most infinite loop scenarios" and give a rule: if a target is declared, it should differ from the current state node. Both of those targets do differ. It hangs anyway.

bun run src/verify-behaviour.ts

PASS  a typo'd target throws at createMachine(), before any actor exists
      Invalid transition definition for state node '(machine).a':
Child state 'typoState' does not exist on '(machine)'
PASS  an unhandled event changes nothing and warns nothing
      value a -> a, can() false, warnings 0
PASS  manipulation check: the same actor DOES move on an event it handles
      a -> b
PASS  a targetless self-transition preserves the active child
      {"process":"step3"}
PASS  a self-transition with an explicit target resets it to the initial child
      {"process":"step1"}
PASS  an always/always cycle constructs fine and then never finishes starting
      printed: "constructed"; killed after 5s

The third line is there because the second is a claim about an absence, and an absence proves nothing unless you show the thing was listening.

Lines four and five are one character apart: an explicit target re-enters the state even when it is the state you are already in.

A hand-written transition table does catch the bogus target that XState's types miss, but only if you tie its targets to the state union:

type Table = { [S in State["tag"]]?: { [E in Event["type"]]?: State["tag"] } };

Write the typo into a free-standing literal type instead, with no tie back to State, and it compiles clean. The check comes from that line, not from having used a union.

When not to reach for one

The test is mechanical, and you can run it on your own code in about a minute: count your nested states and your parallel regions. If both are zero, you have written a state machine and paid for a statechart.

nested states?      no  ─┐
parallel regions?   no   ├─▶  you have a state machine. Write the switch.
`after` timers?     no   │
history states?     no  ─┘

any of them yes    ─────▶  you are using the notation. Keep it.

Timers and history states are on that list because XState hands you both as primitives, after being the one-line version of a delayed transition. You can write either by hand, so this is a question of what you are getting for the dependency rather than of what is possible. And it tests the library, not the idea: a flat machine is a fine thing to have, it just does not need fourteen kilobytes to be one.

In October 2025 the mapping library lonboard opened an issue saying "The current XState implementation is overkill for our simple UI interactions". The migration to Zustand merged that December. The machine they deleted, pinned at the commit before the merge, was 180 lines, three top-level states, six event types, and zero nested-states blocks.

Flat. It was a state machine the whole time.

The honest code delta is small: 375 lines of application source removed, 283 added, so about ninety lines net. The pull request header says +1425/-488, but roughly eleven hundred of that is new Playwright tests, and quoting it as a code-size result would be dishonest. Their own stated goal was not fewer lines. It was to "Lower barrier to entry for JS developers".

The vendor says something close to the same thing, which is stronger evidence than a skeptic saying it, because the vendor has every reason not to. The XState README tells you to start with @xstate/store "if you just need a store" and graduate later. When they announced that store in 2024 they wrote that teams were using XState "for simple data updates, where using full state machines may be overkill". The author's own rule, from an April 2026 thread: statecharts "are most useful when you have behavior where the answer to 'what happens next?' depends on both the current state & the event".

Leaving is not free, either. In a 2024 discussion titled "Need suggestions on migrating away from XState", the poster opened with "XState is just way too sophisticated for our needs" and, ten months later, wrote: "We haven't done the migration because this is a big undertaking and we don't have the resources for it at the moment."

And one widely shipped engine threw one of the two ideas away on purpose. Zag.js, which drives the components in Chakra UI and Ark UI, says "We don't follow the SCXML specifications" and instructs its own contributors to "Avoid using complex machine concepts like spawn, nested states, etc." Finite states, yes. Hierarchy, no.

What else is there

A tagged union and a switch. Already shown. For a flat model it is the right answer, it is shorter, and it types per-state data better.

Zustand, Redux, @xstate/store. All stores. Worth knowing that @xstate/store is not a small statechart: the words states, initial, parallel, guard, entry, exit and history appear nowhere in its type surface. It is context and events. And @xstate/fsm, the small official state machine, is deprecated, so the ladder now goes from nothing to a store with no states to the full fourteen kilobytes, with nothing in between.

Behavior trees. The competitor that won an entire industry. Similar to hierarchical state machines, except the building block is a task rather than a state, which turns out to suit game AI better. Halo, BioShock, Spore; Unity and Unreal both support them.

TLA+ and friends. A different altitude: you model the algorithm and check the model, rather than running it. The AWS team's report also states the ceiling that applies to everything in this post, statecharts included: "TLA+ cannot verify code, only algorithms. Code can have bugs that the spec does not have."

Durable workflow engines. AWS Step Functions calls its workflows state machines outright, and it does the thing a statechart in a browser tab cannot: a run stays alive for up to a year, and you are billed per transition. XState hands you a JSON snapshot and restores from it, which is not the same promise, because you own the storage and the uptime.

One piece of prior art deserves naming, because the shape of this post is not new. In July 2020 Matt Pocock built a modal three ways, counted the refactors each version needed under a changed requirement, and got 4, 4 and 2. Two things about it. The new requirement was a timed transition, which is the one case XState answers with a one-line primitive, so the setup favours the tool. And the promised part two never came. What I did not find anywhere is a discriminated union of states entered as a real contender, or anybody reporting a count instead of a verdict.

So: count your nested states. Count your regions. If you have neither, write the switch, and know that you are in good company. If you have both, and you are writing savingConfirming by hand, you already have a statechart. You are just spelling it out one combination at a time.

Your agent writes Python. The Ruby rule cuts that by a third.

Leonid Svyatov — Thu, 06 Aug 2026 12:33:48 +0000

Lucian Ghinda published a post arguing you should tell your coding agent to write its throwaway scripts in Ruby. Here is the block he tells you to paste into your agent's instruction file, in full:

## Scripts

Write throwaway and utility scripts (data munging, one-off migrations,
file renames, glue code) in Ruby, even in projects written in another
language. If it needs a pipe, a loop, a conditional, or more than one
line, it is a script: write it in Ruby, not Python, Node, or bash.
Single self-contained commands (`grep`, `git status`) are fine as-is.

Use only the Ruby standard library. If a gem would clearly save
significant effort, stop and ask before using it.

Put temporary scripts in a scratch or temp directory, not the repo
root, and delete them when done unless asked to keep them.

I pasted it into my global CLAUDE.md the same evening. His argument is about review: he reads Ruby daily, so when the agent writes Ruby he stays a reviewer instead of nodding at a diff. He gives three reasons and not one of them is cost. So I went looking for the number he left out.

"Does the rule save tokens" only means something against what the agent writes otherwise, so the first thing I had to do was take the block back out of my global config. An agent that already carries the rule cannot tell you what it would do without it.

Measuring an agent without your config in the room

Every arm below runs through claude --safe-mode on Claude Opus 5, which loads no CLAUDE.md, no skills, no plugins and no hooks. Two arms deliberately skip that flag, and I name them where they appear: they are the ones that measure what my own setup does to the result. It is worth knowing that my global config alone still carries a line telling the agent to write the minimum code that does the job, and another preferring bun over node.

Four tasks, one for each kind of script the rule names: munge a log, rename a key across a tree of config files, renumber a pile of screenshots, turn one CSV into another. I took them from his list rather than inventing my own, so I could not quietly pick ground that suits Ruby.

Three things about the setup are worth knowing before any number lands. All three are choices I made, and all three are arguable:

No arm pastes the rule itself. Each names a language and the standard-library constraint directly, which is what the rule produces rather than its own text.
The bash arm may not use jq, since the rule says standard library only and jq is a separate install.
The Ruby arm alone was told one of its brevity idioms is available. That is a thumb on the scale for Ruby, worth about 20 of its 1660 bytes.

Nothing is counted until it is proven equivalent. Every implementation of a task runs against one reference and must produce the same bytes on stdout and the same digest for every file it leaves behind. Comparing the length of programs that do different things is meaningless, so that check gates everything:

ruby src/run.rb text

  t1_logs     count requests and errors per path in an access log    53 impls  identical
  t2_config   rename one key across a tree of .env files, decoy key left alone 53 impls  identical
  t3_rename   renumber screenshot-N.png to zero-padded shot-NNNN.png 53 impls  identical
  t4_csv      filter a CSV to rows with stock, compute totals, write a CSV 53 impls  identical

EQUIVALENT: every implementation matches one reference (stdout + output tree)

The baseline: it writes Python

Ten runs, same four specs, no language named anywhere. Five in the clean room, five with my real setup after the rule came out.

The prompt is not blind, and I should say so. It asks for one sentence on why the agent chose what it chose, which tells it the choice is being watched. A blind version is the run I would do next.

All ten wrote Python.

Not one reached for Ruby, or bash, or JavaScript. The reasons they gave were about the standard library: preinstalled everywhere, handles line-terminator preservation and fixed-decimal formatting without dependencies. So the rule is not choosing between Ruby and some abstract field. It is displacing Python, every time.

Five of those runs had my setup loaded and still chose Python, which is only worth reporting if the setup was genuinely in the room. It was. Asked directly, a session in that condition quotes my CLAUDE.md back at me, and the same setup moves the byte counts by up to 59% below. It was read. It simply has nothing left to say about language once the rule is out of it.

That makes the cost question concrete, and the answer is not close:

bytes, four scripts, neutral prompt	Ruby	Python	bash	JS
source	1660	3644	2333	3231
vs Ruby	0%	+120%	+41%	+95%

Ruby is the shortest of the four, and in the clean room the agent's Python runs to more than twice the source for the same verified behaviour.

That number is condition-dependent, and my own environment is much less flattering. Run it again with my real setup loaded and Python's lead over Ruby drops from 120% to 18%. What the rule buys you depends on what else is already shaping how your agent writes:

the rule's saving	unprompted default	told Ruby	cut
clean room	3595	1660	54%
my real environment	1932	1375	29%

Both rows are five runs against one, measured the same way. The clean-room row isolates the rule. The bottom row is where you actually are, if your agent is configured at all, and it is the number I would plan against.

The counter drops comments and blank lines but keeps imports, since having to import is a real cost of the language. It also keeps Python docstrings, which is a point against Python that a # comment would not have cost it. Those are 8% of the clean-room Python total, and removing them leaves it 101% larger than Ruby instead of 120%.

Nor is the gap all Ruby. Most of that 120% is not the language, it is what the agent wraps around it: the docstring, the main(), the if __name__ guard, the line-ending bookkeeping. Discourage those habits and Python's lead falls to 18%, near the 36% I get writing both by hand.

What the difference looks like

One task, the config migration, as the neutral prompt produced it. Ruby first:

root = ARGV[0]

Dir.glob(File.join(root, "conf", "*.env")).sort.each do |path|
  content = File.read(path)
  renamed = 0

  rewritten = content.lines.map do |line|
    if line.start_with?("CACHE_TTL=")
      renamed += 1
      "TTL_SECONDS=" + line[("CACHE_TTL=".length)..]
    else
      line
    end
  end.join

  File.write(path, rewritten) if renamed > 0
  puts [File.basename(path), renamed].join("\t")
end

That is the whole program. Read it once and you know it is right.

Python's version of the same task runs to 38 lines. Here is the middle of it, the loop that does the work:

        renamed = 0
        lines = text.splitlines(keepends=True)
        for i, line in enumerate(lines):
            body = line.rstrip("\r\n")
            ending = line[len(body):]
            key, sep, value = body.partition("=")
            if sep and key == OLD_KEY:
                lines[i] = NEW_KEY + "=" + value + ending
                renamed += 1

text is the file's contents; OLD_KEY and NEW_KEY are the two key names, defined at the top of the file. That is the same loop as the Ruby, plus manual line-ending bookkeeping, wrapped in a main() with a docstring, four imports and an if __name__ guard. None of it is bad Python. It is just more of it, and the count agrees:

neutral prompt	Ruby	Python	bash	JS
lines	56	108	101	89
distinct words	104	155	125	118
longest line	80	81	65	73
punctuation, share of non-space characters	24%	24%	37%	29%

Ruby wins the two that track reading effort, and loses longest-line to bash. I picked these four before running them and I report all four whichever way they fall, because there is no accepted way to measure readability and a metric chosen after the fact measures the author.

bash only looks cheap when you ask it to be

Told nothing, the agent writes careful bash: shopt -s nullglob, an explicit sort, a temp file per input, and a check for whether the original ended with a newline so it can put it back. That is 2333 bytes, 41% longer than Ruby.

So I ran the neutral prompt a second time with one thing changed: --safe-mode off, so my real setup loads instead of the clean room. Same prompt, same specs, same fixture.

bytes, neutral prompt	Ruby	Python	bash	JS
clean room	1660	3644	2333	3231
my real setup loaded	1375	1627	945	2163
change	-17%	-55%	-59%	-33%

Every language shrinks, and the winner changes. In the clean room Ruby is shortest. Load my setup and bash is shortest by 31%, which is the tidy "just use bash" result, produced entirely by my own environment.

I cannot pin that on one sentence, and should not try. Turning --safe-mode off restores my CLAUDE.md, skills, hooks and plugins at once, and one of those plugins injects a persona built around writing the shortest thing that works. The honest label on that row is "everything I normally run with".

Both numbers are real. They answer different questions, and only one of them was the question I asked.

How few words buy terse code

If one line of configuration moves the numbers that far, what is the cheapest instruction that moves them on purpose? I ran a ladder: same specs, same clean room, one agent per language per rung, with only the instruction changing.

instruction	words	Ruby	Python	bash	JS	all	vs none
(nothing)	0	1660	3644	2333	3231	10868	0%
"Be terse."	2	1275	1830	906	2347	6358	-41%
"Golf it."	2	735	1033	743	1369	3880	-64%
"Shortest code possible."	3	799	1151	659	1448	4057	-63%
"Write the shortest X code possible. Minimise source length aggressively."	10	697	1062	639	1322	3720	-66%
the same plus six explicit rules	36	685	863	532	1243	3323	-69%

Two words get you 64 of the 69 points available. The 34 words after them buy the last five, which at one run per cell is inside the noise: adjacent rungs swing by up to 11% per language, and the 2-word rung already beats the 3-word one.

The words themselves matter far more than how many there are. "Be terse." and "Golf it." are both two words, and "Golf it." produces 39% less code overall, and less in every one of the four languages. "Golf" is a term of art, and it drags in everything the phrase "code golf" implies. "Terse" just asks politely.

If you want an agent to write compact code, "Golf it." is the whole prompt.

What terse code costs

Here is that same config migration again, at the bottom of the ladder:

Dir[ARGV[0]+"/conf/*.env"].sort.each{n=0;File.write(it,File.read(it).gsub(/^CACHE_TTL=/){n+=1;"TTL_SECONDS="});puts [File.basename(it),n]*"\t"}

One line, 144 bytes against 409, and it passes the same byte-for-byte check.

Three things in there need decoding:

it is Ruby's implicit block parameter, so each it is the current filename. It needs Ruby 3.4 or newer. On anything older this line is an error, not a slow read.
The gsub block both counts a match and returns the replacement, so n grows as a side effect of building the new text.
[File.basename(it),n]*"\t" is an array joined by a tab, because * on an array is join.

I had to look twice, in my own language.

The line counts collapse and the lines themselves get worse. Ruby's longest line goes from 80 characters to 151, JavaScript's from 73 to 199, and punctuation climbs from 24% of the non-space characters to 37%. You are not buying compact code. You are buying dense code, and paying in the thing the rule was adopted for.

Then I pointed all 152 implementations at a directory with a space in its name, the six rungs plus the hand-written set as a control. One rung broke, and it is the expensive one: every bash script written under the 36-word instruction failed, all four, while the bash from every shorter rung survived.

awk '{e[$7]+=$9>=400;t[$7]++}END{for(p in t)print p"\t"e[p]"\t"t[p]}' $1/logs/access.log|LC_ALL=C sort -t$'\t' -k2,2nr -k1,1

That $1 is unquoted. Three of the four exit 0 anyway, because a failing awk piped into sort reports the exit status of sort. Two of those three print nothing at all and the third prints -1. The error does reach stderr, so a person watching the terminal sees it. Anything checking only the exit status does not.

So the last 34 words of instruction bought five percentage points of length and broke every bash script they touched. "Golf it." did not.

The limits

Length is bytes. I did not run a tokenizer over any of these sets, so every percentage here is a byte percentage, and how closely it tracks a token bill is an assumption I have not tested.
One agent run per language per rung. The direction is consistent across four languages and six rungs. The exact percentages are not.
Four tasks, taken from the article's four categories so I could not pick favourable ground, but still four.
Ten runs is enough to say the default is Python here. It is not enough to put a number on how often.
The clean room removes configuration, not the model's own priors. "No config" is the honest floor I can reach, not a neutral universe, and a different model may default somewhere else entirely.
The spaced-path failure is one awkward path on one machine. It shows the failure mode, not a rate that transfers.

What I would actually tell you

Keep the rule. It wins on cost alone, which is not the argument its author made for it: against Python, the language your agent picks when you say nothing, it cuts source by about a third in a configured setup and by half in a bare one.

Do not reach for a terseness instruction instead. Those cut more than the rule does, but they buy density, not brevity: less code that nobody can read, in a language you did not choose. Push far enough down that ladder and it broke four bash scripts on a path with a space, though "Golf it." itself did not.

Override it in three places. When the library only exists elsewhere, which is Ghinda's own exception. When the script has to run where Ruby is not installed, which the baseline runs raised themselves by picking Python for being preinstalled everywhere. And when the job is one honest shell command, which the rule already exempts.

Ghinda's own reason is still the better one, and it is the one no table here can settle. Reviewability is a fact about the reader. Those same numbers would hold for someone who cannot read Ruby at all, and for them every row above stops meaning anything.

One thing carries past Ruby. Every number here moved, and two of them reversed, depending only on whether my own setup was loaded. If you benchmark an agent, take your config off first, or you are measuring your config.

I wrote down 61 rules, then failed my own repos

Leonid Svyatov — Tue, 04 Aug 2026 13:54:40 +0000

Nobody starts a library because they wanted to write a SECURITY.md.

You start it because there is a thing you want to exist. Then you publish it, and a second job arrives that nobody signed up for: issue templates, a code of conduct, pinned action SHAs, a changelog that survives contact with a release, a publish job that does not leave a long-lived token lying around, and a README that still tells the truth eighteen months later.

That is the boring half. It is mostly mechanical, and it decides whether a stranger with a good patch can figure out how to send it to you.

So I wrote it down. oss-kit is 61 rules about that half of the job and nine agent skills that fix them. Then I pointed it at two repositories of my own. The first failed 27 rules. The second I had already put through the fixing loop, so it is the one that shows what is left at the other end.

What the boring half contains

Before you can hand the work off, somebody has to say what the work is. Seven areas:

Area	Rules	What it covers
Documentation	10	README order, claims that match the source, prose that is not marketing copy
Community	9	License, contributing guide, code of conduct, security policy, issue forms, governance
Continuous integration	6	What runs on push and on every change request, on which runtimes, and whether tests exist
Security posture	15	Pinned action SHAs, workflow permissions, branch and tag rules, lockfiles, signed tags
Release and publishing	7	Trusted publishing, provenance, approval gates, bills of materials
Changelog and versioning	7	Keep a Changelog structure, the right bump, release notes that match
Agent skills	7	Layout, frontmatter, licensing and portability, if your repo ships skills

Two areas are gated by a precondition rather than by a setting. Publishing needs a repository that ships a built artifact, and it then splits again: on the registry-push track every rule applies, and on the tag-published track, where the registry reads your forge and no publishing credential exists at all, four of the seven have nothing to attach to. Go modules and Packagist live on that second track. The agent-skills area needs a SKILL.md somewhere in the repo.

That scoping is most of what an audit spends its time on. On the untouched repository below, 18 of the 61 rules came back not applicable, each with the reason: no skills, one principal holding every merge path, a release carrying no built asset, a package manager that gives you no way to decline dependency install code. That is how you tell a rule that does not reach you from one that quietly got dropped.

On forges: 57 of the 61 rules score GitHub and GitLab alike. Three are GitHub-only, one is GitLab-only, and every rule states which.

Why an agent needed a standard first

A table like that is easy to write and useless on its own, which is the part I got wrong the first time. Ask an agent to improve your README and you get something plausible. It will be well-written. You will have no way to tell whether it is better, because "better" was never defined, and neither of you can point at anything.

So every opinion in oss-kit lives in one file as a numbered rule, and every rule carries a line naming the evidence you can go look at. Not "the README should be welcoming" but: the first paragraph after the title is a single sentence naming what the project is, and it appears before any table of contents or badge row. That is a claim you can go and check for yourself, and tell me I am wrong about. "Welcoming" is not.

The same discipline is what makes the kit reach past the language I happen to write in. Eleven ecosystems get a real answer rather than a footnote: npm, PyPI, RubyGems, crates.io, Go modules, Packagist, NuGet, Maven Central, Hex, pub.dev, and container images. Seven of the nine skills carry one file per ecosystem, 77 files in total, each ending with the date its source was last read. A script fails CI on a missing file, a file no roster lists, a declared heading left empty, or a date that does not parse.

Whether a library commits a lockfile is not one question with one answer, so the files answer it per ecosystem, each citing the documentation that settles it.

This is also the honest answer to "why not just use OpenSSF Scorecard." Scorecard is good and I use its data, but it is security-scoped: branch protection, pinned dependencies, code review, fuzzing. It has no opinion about your README, your changelog, or whether a contributor can find out how to run your tests.

CNCF's CLOMonitor does have those opinions, and it is the closest thing to this that already exists. It scores documentation, community files, licensing and security posture against a public checklist. It is also a hosted dashboard aimed at foundation-hosted projects, it does not read GitLab, and it stops at the report. Nothing in it hands a finding to the thing that fixes it.

What you actually get

clsx-ruby is a gem of mine: green CI, published to RubyGems, six releases, and I would have told you it was in decent shape. I audited it a week ago, fixed none of what it found, and let exactly one commit land since, a development-dependency bump. So the report below is that same repository, untouched.

cd clsx-ruby
npx skills add svyatov/oss-kit --skill '*'

Then, to the agent: Audit this repository against the oss-kit standard.

Sixty-one verdict lines came back: 16 pass, 27 fail, 0 unknown, 18 not applicable. Every fail carries the evidence it read and the skill that owns the fix. Three of them, verbatim, with the Check: text each one quotes cut for length:

- R-COM-04 fail no `SECURITY.md` at the repository root, in `.github/`, or in `docs/`
  Fixed by: oss-community
- R-SEC-11 fail rubygems: `dependency-graph/sbom` lists 11 packages, every one a direct `Gemfile`
  entry, plus the 3 actions; the on-disk `Gemfile.lock` resolves 29 gems, so the 18 transitive
  dependencies are watched by nothing, because no lockfile is committed for the graph to read.
  `vulnerability-alerts` answers 204, so the alerting itself is enabled
  Fixed by: oss-harden
- R-PUB-03 fail rubygems: `https://rubygems.org/api/v1/attestations/clsx-ruby-1.2.0.json` answers
  200 with an empty array, so the registry serves no attestation for the exact published version
  Fixed by: oss-publish

A few of the twenty-seven, in the order that they bother me:

Nobody can report a vulnerability in this gem privately. There is no SECURITY.md, so a person who finds something either opens a public issue describing it or gives up.

Eighteen of the twenty-nine gems it resolves are watched by nothing. The dependency graph reads the Gemfile, the Gemfile.lock is in .gitignore, so everything transitive is invisible to the one tool that would tell me about an advisory.

Three of its actions are pinned to a tag rather than a commit. actions/checkout@v4, ruby/setup-ruby@v1 and codecov/codecov-action@v5, each a name whoever publishes it can repoint whenever they like.

The README opens with "The fastest". There is a benchmark table that backs that up, 55 lines down, past the point where a reader decides. A superlative with its evidence out of reach is the exact thing I wrote a rule against, in a README I wrote myself.

The published gem has no attestation. Nothing ties clsx-ruby-1.2.0.gem back to the commit it was built from. The audit did not conclude that from a 404, which is the difference between a fail and an honest unknown: a guessed URL answering 404 proves nothing about the gem.

The report is a file now, oss-audit-report.md, written at the root of the repo and untracked. It carries a verdict line for all 61 rules, passes included, and it ends by grouping the 27 fails into seven pull requests with the dependencies between them spelled out. Community files first, because SECURITY.md is what the security rules build on. Commit the lockfile before the rule that reads the dependency graph, because one closes the other. Publishing last, because two of its rules can only be verified against a newly published artifact.

Then you fix them

None of that is work that gets done by reading a report, which is what the other repository is for.

sec_id is a gem I have maintained for years: 17 published releases, every community file present, contributing guide, code of conduct, security policy, issue templates. When I first ran this audit on it, against a standard that held 46 rules, it scored 19 pass, 18 fail, and one honest unknown.

Then I ran the fixing loop on that report. Eight pull requests, which I grouped by owning skill myself, because the report file did not exist yet: pin the actions and commit the lockfiles, publish through trusted publishing, state the governance, give the README a differentiator, resolve the changelog version links.

Same prompt, same repo, seven days and 61 rules later:

cd ../sec_id

Audited 51 applicable rules: 44 pass, 7 fail, 0 unknown, 10 not applicable.

Eighteen fails to seven, while the standard grew by fifteen rules underneath it. The unknown closed too, and on real evidence: the sigstore bundle's digest matches the published gem's checksum, and the certificate names the workflow and the tag it was built from.

The standard moving did not only cost me. R-COM-06 wanted a CODEOWNERS file and sec_id failed it on the first run. It now scores not applicable, because the rule gained an exclusion for a repository where one principal holds every merge path. No file was ever written. Some of the drop from eighteen to seven is the rule moving rather than the repo.

The seven survivors are what a fixing pass could not close.

Two are rules that did not exist when I fixed it, and the next section is about them. Two are failures the fixing caused: one pull request added a SKILL.md, which pulled the whole agent-skills area into scope, and two of its seven rules fail. One is a rule whose text changed under a config I never touched, and one is a check I think is simply wrong. Those two get the sections after that.

The seventh is the one I would call plain old debt. R-CHG-05 wants a removal to have been deprecated in some earlier release, and two of sec_id's major versions removed things that never were. Both are published, so nothing can go back and deprecate them now. The contributing guide already states the gap outright, which is about as honest as that gets.

Fixing a repository is how you find the rules that were never reaching it.

The standard moves under you

Fifteen rules in seven days, and both repositories fail the same two new ones.

R-SEC-14 asks your dependency updater to wait before proposing a version published minutes ago, through Dependabot's cooldown or Renovate's minimumReleaseAge. R-SEC-13 asks for a ruleset over refs/tags/* that blocks tag updates and deletions and names who may create one. Both repos guard their default branch, neither guards a tag, so a released version number can still be repointed at a different commit. That is the one change a version number exists to make visible.

The cooldown rule is the one I would have defended hardest, so here is what writing this post did to it.

The argument goes: what ends a registry compromise is other people looking, and that takes hours. An updater with no cooldown opens its pull request inside that window, so the project that merges its bumps promptly is the one that installs the bad version first. Diligence becomes the exposure.

Both my repos fail on a Dependabot config with no cooldown block, which is a fair reading of the check. But GitHub applies a default cooldown of three days to version updates when you have configured none, and three days outlasts the window the rule was written about. The exposure I just described is not present in either repository.

Renovate is where it survives. Its minimumReleaseAge defaults to null, so a Renovate repo with nothing set waits zero days. Same rule, same fail, two situations that are not remotely alike, and the rule text cannot tell you which one you are in. I have filed that against my own standard.

What is left of the rule is still worth having, and it is a narrower thing than I wrote down: a written setting does not move when the platform changes its default, and it is a decision somebody can audit.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "bundler"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7
      semver-patch-days: 3

That is the whole fix, and both of my repos still do not have it.

A third new rule reaches neither repository and is the one I would read first. R-SEC-15 asks CI to install dependencies without running the code they ship. That is the step the September 2025 npm worm used to spread. Unit 42's writeup records that the malicious versions "contain a worm that executes a post-installation script." Installing was enough.

It falls outside eight of the eleven ecosystems rather than failing them, RubyGems among them, which is why both gems score it not applicable. Cargo, RubyGems and Hex give you no documented way to decline. Maven, NuGet, Go modules, container images and pub.dev run nothing during resolution at all.

There is a cost to writing rules this fast, and one of sec_id's seven fails is it. R-CI-01 scores a trigger block that has not changed since February. What changed is the rule: a pull_request trigger carrying a branches: filter now fails where it used to pass. The project is below 1.0.0, so an incompatible change ships in a minor release, and a repo that passed yesterday can fail today.

What it will not do

The rules are the part you can argue with. The scoring is the part I would argue with.

Five rules ship with a real checker, a dependency-free script that either exits 0 or does not. The other 56 are scored by a model reading a check line. That ratio has moved the wrong way: the standard grew by fifteen rules and the checker still covers the same five.

The kit did gain five scripts in that time, and not one of them scores a rule. They collect the facts a check line refers to. The one script that returns a verdict is the one it already shipped with.

A collector can also be wrong. On sec_id, the bundled one reported two CI jobs where the repository has seven, with a steps: 0 beside each as the tell. The rule it fed passes either way. An audit that filtered on that output would have scored a five-job blind spot without noticing.

The model half is worse. One check asks that every code block name the file or tool it goes to. sec_id's README fails that on roughly 35 REPL-style blocks under a literal reading, and passes under the intent reading.

A check that would fail essentially every library README ever written is telling you about the check, not the README. Another rule passed on judgement while the bundled validator exits 1, because counting it would have reported one gap twice.

Then there is the one I did not see coming. The kit added a closing step that re-audits after the fixes and diffs the two reports, so a fix that broke something else surfaces as a verdict that went from pass to fail.

I could not run it. The first audit predated the report file, so its verdicts were chat output and nothing else. A verdict nobody wrote down cannot be compared, and my own repo is the worked example.

The nine skills

Skill	What it does
`oss-audit`	Scores the repository and routes each gap to a skill.
`oss-community`	Writes every community file, from the license to issue forms.
`oss-readme`	Orders the README and checks its claims against the source.
`oss-ci`	Writes the test, lint, and build jobs for either forge.
`oss-harden`	Pins action SHAs, trims permissions, and guards branches and tags.
`oss-publish`	Publishes to eleven ecosystems, gates the run, and signs it.
`oss-changelog`	Keeps CHANGELOG.md, picks the bump, writes release notes.
`oss-writing`	Fixes the sentences in commits, reviews, docs, and issues.
`oss-skill`	Fixes the structure and portability of the skills you ship.

What these skills actually do is refuse things, and the refusals are why I let them near my repositories at all. (These are design commitments written into the skills, not behavior this post tested end to end.)

The missing SECURITY.md goes to oss-community, which will not write security@example.com, or any plausible-looking address nobody confirmed, and will not promise a response window you never agreed to. If the repo does not tell it where security reports should land, it stops and asks me. It also prefers GitHub issue forms over Markdown templates, because a template made of Markdown headings cannot require a field, so a contributor can delete every heading and submit an empty issue.

The README's out-of-reach superlative goes to oss-readme, which matches every claim in a README against the manifest, the source and the CI config. It also will not pick your README's facts for you: it sweeps the repo, sorts candidates into the questions a reader has, lists what it rejected and why, then stops and makes you choose three to five. Left alone, a writer picks whatever the source tree makes easy, which is how a facts list ends up describing how a project is built instead of what it does.

The three actions pinned to mutable tags go to oss-harden, which pins them to full commit SHAs. What it will not do is pin a dependency whose origin it could not establish in the first place. Pinning gives you the same unverified code at a known revision, and the next person to read that line will assume somebody vouched for it. It reports that as an observation with no rule ID attached, because no rule reaches it.

The unattested gem goes to oss-publish, which moves publishing into a workflow that authenticates without a stored token. It will not fake a missing approval gate with some third-party action it found; it reports the rule as unmet and says so.

oss-writing is the one I use before writing anything at all. It gives a commit or a pull request a body only when one of six named triggers applies, and the default is no body. It also refuses to add Co-Authored-By: Claude trailers, on the grounds that a trailer records who is accountable for a change and a tool cannot be.

The rules you will argue with

All of which assumes you accept the rules doing the routing. I am not going to tell you these are 61 uncontroversial best practices, because several of them are not.

The README rule puts your badge row below the opening sentence. PostCSS and Nano ID put badges above, and they are more successful projects than anything I have written. The skill concedes the divergence in writing and states the condition under which it holds.

The prose rule bans every emoji character in project documentation. I argued against my own rule on this one, wrote "banning emojis in open source might be way too strict, emojis are fun," and then never changed it.

Two of the agent-skill rules are deliberately stricter than the Agent Skills specification. The spec permits Python, Bash and JavaScript in a bundled script and leaves the choice to the implementation; oss-kit allows only sh or dependency-free Node. The spec marks the license: field optional; oss-kit requires it, because an installer may extract one skill directory without your repository's license file. That second one is a rule sec_id now fails, which is how I know it bites.

And the versioning rule overrides SemVer during 0.y.z, using MINOR for incompatible changes rather than forcing a premature 1.0.0.

You can read every rule, with its reasoning and its check, without installing anything. That is deliberate. Disagreeing with rule R-DOC-05 by name is a better outcome than nodding along to a prompt you never read, and there is a rule-proposal issue form for doing something about it.

Where to start

Install the whole kit:

npx skills add svyatov/oss-kit --skill '*'

Or one skill at a time, if you only want the README one:

npx skills add svyatov/oss-kit --skill oss-readme

In Claude Code or GitHub Copilot CLI, type these two at the prompt instead:

/plugin marketplace add svyatov/oss-kit
/plugin install oss-kit@oss-kit

Nine hosts are recorded, each with the paths it reads and the date that was checked. Two of them have no command-line install at all, so placing the directory is the install. Then ask your agent:

Audit this repository against the oss-kit standard.

Authenticate gh before you do, because a checkout cannot answer what the audit needs to score. Rulesets, environments, the dependency graph and release bodies are all forge reads. Without them those rules come back unknown rather than wrong, which is the correct answer and a much thinner report.

Read the report, then run whichever skill each line named. The audit changes nothing it scores; it writes one file. The skills do change things, and they are not silent about it: they stop and ask when a file needs a fact your repository does not contain, they propose forge settings rather than changing them under you, and they finish by listing every file written or proposed and every fact that came from asking rather than reading. Skills install independently, so you can take one and ignore the rest.

If the repo is brand new there is nothing to score yet, so skip the audit and go in order: oss-community for the license and community files, oss-readme, oss-ci, oss-harden, oss-changelog, then oss-publish if you ship a package.

Run it on something you already maintain. Not a toy repo, the one you would be embarrassed to have someone read. You will get a list. Some of it you will disagree with. The rest is the boring half, finally written down, in an order somebody thought about.

Then hand it to the agent, because you did not start this project to write a SECURITY.md.

Kubernetes earned its security badge in 2017 and never came back

Leonid Svyatov — Fri, 31 Jul 2026 17:23:07 +0000

Kubernetes has an OpenSSF Best Practices badge. It earned that badge on 16 August 2017 at 14:52:28 UTC, and nobody has touched the entry since. The save that earned it is still the last anyone made: the two timestamps sit three milliseconds apart, because one save wrote both.

The badge on that page today looks exactly like a badge earned this morning. It carries no date.

bestpractices.dev has been running for a decade, the CNCF requires it before a project can graduate, and it had never crossed my desk. So I went and read it properly: the criteria, the Rails app behind it, and the daily statistics it has been publishing at a public URL the whole time. This is what I found, including the part the program's own maintainer raised in 2024 and nobody has fixed.

Every number here was fetched on 31 July 2026, by crawling the site's own JSON API and its published daily statistics. They move daily, so check them rather than trusting mine.

What the thing is

It is a questionnaire. You answer a list of questions about how your project is run, and if you answer enough of them the site gives you a badge image for your README.

It is free, it takes no review board, and it works for any project anywhere. The Linux kernel's entry points at git.kernel.org. GitLab's own repository holds one. Working anywhere is the badge's real advantage over the automated scanners.

There are two ladders now, which is the first confusing thing a newcomer meets:

  METAL (2016)                    BASELINE (2026)

  passing   67 criteria           baseline-1   24 controls  \
     |                            baseline-2   19 more       > OpenSSF Baseline,
  silver    55 more               baseline-3   21 more      /  MUST-only controls
     |
  gold      23 more

  3,080 projects at passing       223 at baseline-1
    262 at silver or better       103 at baseline-2
     86 at gold                    44 at baseline-3

Same form, same login, two unrelated series of questions. The metal ladder is cumulative: a gold badge is 145 criteria deep.

Anyone with an account can create an entry for any project, and nobody checks that you own it. The first person to file owns it, though GitHub committers on the repository you name can edit it too.

Where it came from

Heartbleed, April 2014. Two weeks after the bug went public the Linux Foundation announced the Core Infrastructure Initiative, and the badge was one of the things that initiative produced.

The repository's first commit is dated 22 July 2015. Dan Kohn, two files, 24 lines: an MIT license and a README containing nothing but the project's name. Two weeks later David A. Wheeler pushed the first draft of the criteria, and the document says out loud what the thing was always going to be:

The goal is to eventually create a "badging" program where OSS projects that meet the criteria can voluntarily self-certify that they meet the criteria and then be able to show a badge.

Self-certify. That was the plan on day one, and it is still the plan.

Greg Kroah-Hartman opened the first pull request on 10 August 2015 to delete the code-coverage requirement, arguing coverage "is not a good metric for any sort of assurance other than someone wrote a bunch of tests." It was closed without merging. Eleven days later somebody opened the exact opposite pull request, asking to add coverage back.

The badge went generally available in May 2016. The announcement carries a line that has aged well:

Prior to Heartbleed, OpenSSL failed to meet more than one-third of the CII Best Practices Badge criteria. Today it meets 100 percent.

Then CII became the OpenSSF, and in August 2023 the site moved from bestpractices.coreinfrastructure.org to bestpractices.dev, which is why old badge links point at a domain that no longer names anything.

OpenSSL, ten years on, still holds passing and nothing above it.

What the 67 questions actually ask

The range is wider than "do you have a license." The 67 sort into six groups, and the split says something before you read a single one: Basics 13, Change Control 9, Reporting 8, Quality 13, Security 16, Analysis 8. Most of the form is asking how you run the project.

Four of them, verbatim.

The easy one:

The project sites (website, repository, and download URLs) MUST support HTTPS using TLS.

The one you cannot fake with a config change:

The project MUST have at least one primary developer who knows how to design secure software.

The one that is true or false about the world, not about your repository:

There MUST be no unpatched vulnerabilities of medium or higher severity that have been publicly known for more than 60 days.

And the one that quietly locks a whole class of project out of gold:

The project MUST have a "bus factor" of 2 or more.

That last one is a gold MUST and a silver SHOULD. If you maintain your project alone, silver is reachable by writing a justification and gold is not reachable at all, no matter how good the code is. Gold also wants at least two unassociated significant contributors and half of all changes reviewed by someone other than their author. Gold is measuring your staffing, not your software.

Answering "Met" is sometimes not enough. Across all 145 criteria, 52 require a written justification and 34 require a URL inside it, and an answer that misses either is dropped from your percentage. That burden is almost entirely a silver and gold problem, though: at passing level it is one justification and eight URLs.

Passing is lenient in the other direction too. An unmet SUGGESTED criterion still counts toward your score, so a SUGGESTED item only has to be answered rather than met. And where a justification is required, the bar is MIN_SHOULD_LENGTH = 5. Five characters.

There is also an undocumented convention: a justification beginning with // is treated as a comment rather than an answer, and it appears nowhere in the docs or the interface strings.

How long does it take? The one clean public figure comes from Marc Wrobel, who filled one in for his own library and said it took "3 to 6 hours to answer all the questions." Roscoe Bartlett, teaching the badge to scientific-computing groups at Sandia, puts reading the criteria alone at more than half a day. The Linux Foundation's 2016 press release claimed "generally, in under an hour," which I can find no evidence for.

Sandia's FIREWHEEL went from entry creation to passing in six hours and two minutes, one sitting. BizHawk opened its entry in November 2021 and is still in progress.

You do not have to type everything. The site reads your repository and pre-fills what it can, and you can hand it a .bestpractices.json file or a security-insights.yml in the repo instead. Autofill only works against GitHub.

Does anyone actually check?

The maintainers answer this themselves, in the repository, and their answer is more careful than most of the criticism I found:

That means that the badge is not strictly self-certification, instead, the badge is merely based on it.

I went to find out how much work "merely" is doing. The app runs a set of classes it calls detectives, which read your repository and propose answers. Most of them only fill in blanks. Three of them can overrule a human being who claimed "Met", across five criteria: the HTTPS check, the security-headers check, and the license-location check.

Three, and only on GitHub. The license check reads a file listing the app can fetch from nowhere else, so on GitLab or a self-hosted repo the referee is two checks over three criteria.

It also runs the other way, which surprised me. Five answers get forced to Met over whatever the human said, including the license checks.

The bigger check is social rather than automated, and the maintainers lean on it deliberately: every answer and every justification is published on the project page. That is how I found the dead URLs later in this post. Anyone can read what a project claimed and go and look. And the detectives only wake up when someone saves the form, or opens it with an explicit ?reanalyze. Merely looking at a completed entry runs nothing.

So what happens when somebody disputes a badge? There is one good test case: in August 2024 a contributor filed an issue saying Netdata should not hold a badge, because it had begun shipping closed-source dashboard blobs that Debian, Alpine and Fedora had all refused. Wheeler's first response was to check the LICENSE file, see GPL-3.0, and call it settled. Three days later he wrote:

I can point to myself; when this issue was first raised, I went to LICENSE, saw "GPL-3.0", and said "sure, that's OSS".

He escalated it to the project mailing list. Nobody replied. The issue is still open two years later, and Netdata's entry still shows a passing badge, last edited in May 2023.

That is not fraud. It is a volunteer dispute process with one person in it.

The clock that isn't there

Here is the funnel, from the site's own daily statistics:

where entries sit today	entries	share
registered an entry	11,434	100%
at 25% or more	5,785	50.6%
at 50% or more	5,026	44.0%
at 75% or more	4,529	39.6%
at 90% or more	3,863	33.8%
at passing	3,080	26.9%
at silver or better	262	2.3%
at gold	86	0.8%

Those are positions today, not high-water marks, so entries that slipped back are counted where they now sit. Finishing at 26.9% is healthier than the program itself advertises: the repository's README has said "on average only about 10% of pursuing projects have a passing badge" since June 2017, when it was accurate to a tenth of a point. The line has not been edited since.

Now the interesting half. Of the 3,082 entries holding a passing badge (a live crawl, two ahead of the previous night's statistics row above), 1,806 have never been edited since the write that earned it. Not "not edited recently."

gap between earning the badge and the last edit	entries	share
same write (under 100 ms)	1,806	58.6%
100 ms to 1 s	0	0.0%
1 s to 1 min	38	1.2%
1 min to 1 h	340	11.0%
1 h to 6 h	100	3.2%
6 h to 24 h	99	3.2%
more than 24 h	697	22.6%
not classified (two backfill artifacts)	2	0.1%

Nothing at all falls between 100 milliseconds and one second, so the top bucket is a category rather than a cutoff I chose: one save, with the skew inside it running from 0 to 48 milliseconds.

One caveat on that 58.6%, since it flatters the argument: a third of those entries first passed in 2026 and have barely had the chance to come back. Restrict it to badges earned three or more years ago and it is still 53.6%.

Meanwhile 57.8% of passing entries have gone untouched for a year or more, and 15.5% for five years or more. There is no expiry. I looked for one: the scheduled jobs are a statistics task and a reminder mailer, neither recomputes criteria, the recurring-jobs config is an empty stub, and no CI cron touches badges.

While a project sits at 100% the main reminder query skips it, but "never emailed again" would be too strong. Drop below 100% and you re-enter the queue after a 30-day grace, which has happened to 49 entries since they first passed, GitLab and Syncthing among them. A separate warning mailer does reach projects still at 100%: ten were queued the day I looked.

Kubernetes got its last reminder on 15 June 2017. It earned the badge two months later, and nothing has emailed it since.

But are the old answers actually wrong?

"Old" and "wrong" are different words. If a project's practices did not change, its answers did not need editing.

For the famous stale entries, that defence holds. Lynis has not touched its entry since May 2016 and its repository was pushed to this morning. POCO and cjdns are both still alive, and the specific URLs their justifications point at still resolve.

But the decay is measurable. I resolved every hostname in every passing entry's repository and homepage URLs:

entry last touched	entries	dead hosts	share
under 1 year	1,301	3	0.23%
1 to 3 years	860	5	0.58%
3 to 5 years	444	7	1.58%
5 years or more	477	8	1.68%

That is 23 dead hosts across the whole passing set, so read the shape rather than the multiple: single-digit counts per cohort, and moving two entries would break the monotonicity. Opus claims a repository at a host that no longer exists. GnuPG's vulnerability-reporting URL times out. Scraps has had no commits since 2020 and still shows maintained as Met, which is an answer it never gave: that criterion arrived in 2021, five years after its last save.

Staleness is not the only route in, either. One entry edited the day before I looked points its homepage at a host that does not resolve, and another holds passing with a repo_url that is a dead link to a foundation page rather than a repository.

The sharper failure in that table is not decay. Five entries serve a passing badge while claiming sites_https is Met with an http:// URL, which is the exact example the maintainers' own documentation gives of a claim the app will not accept. None of them has been edited since 2016, so those answers were wrong when they were saved rather than rotting later. The check that would strip them today was written in April 2016, before all five saves, but I could not confirm from the commit history whether it was wired into the save path by then. It is also three people rather than five: one of them filed three near-identical entries thirty-three seconds apart.

One thing does re-check you, and it happens without you. When the maintainers change a criterion, a bulk task re-scores every project's stored answers against the new rules, and it writes with touch: false, so your updated_at never moves. On 11 April 2021 nine projects lost their passing badge inside a 72-second window. Two of them had not been touched by their owners since 2016 and 2017.

So revocation exists, and it fires when the maintainers change a criterion. Nothing fires when a project simply goes quiet.

The maintainer already said all this

In March 2024 somebody opened an issue pointing out that dead projects sit in the badge table looking healthy. Wheeler replied:

Also: We do need a way to withdraw badges if no one's checked it in a long time. The "obvious" way to do it is to add a passing criteria like "badge answers have been validated within the last 3 years by a badge applicant". That means every 3 years someone the badge will drop unless someone does something.

The reporter agreed it was a good idea. Then nothing was built. The issue is still open, the roadmap has no expiry item, and it opens by describing the project as "essentially in a 'sustainment' mode."

One related mechanism did ship, in 2021: a new criterion reading "The project MUST be maintained," added outside the usual yearly cycle. The working-group minutes explain the design choice plainly:

it doesn't risk existing badges because the default value is 'Met'

The criterion that exists to catch abandoned projects defaults to claiming they are fine, and the automatic detection Wheeler sketched alongside it was never implemented.

The program diagnosed itself correctly, wrote the roadmap entry calling itself sustainment mode, and has not built the fix.

Who comes back

The write-once pattern is not uniform, and the split is sharper than I expected.

top tier reached	entries	last edit within a day of earning	median gap
passing only	2,820	2,278 (80.8%)	0 days
silver, not gold	176	78 (44.3%)	3 days
gold	86	29 (33.7%)	48 days

The tier a project chases tracks whether it comes back, and I do not think that is virtue. Gold's gates are staffing gates, so gold holders are by definition projects with more than one person available to do the coming back.

Forty-four entries have been edited more than three years after earning passing and also within the last year. The long-horizon group names itself: curl, the badge site's own app, the Linux kernel, GitLab, OpenSSL, Weblate, Jaeger. curl first passed in March 2016 and last edited in May 2026, ten years apart.

Who requires it, and does that work?

The CNCF requires a passing badge for both incubation and graduation. The Academy Software Foundation, LF AI & Data, LF Energy and FINOS each set their own rung.

Then reality. Two CNCF incubating projects have no badge entry at all. Kubeflow's umbrella entry sits at 88%, below passing. Not one graduated Academy Software Foundation project displays gold, although that one is unfair to score: their rule is gold-minus-ten-exemptions, and the site has no way to show that variant, so those projects correctly display passing.

A mandate gets you an entry. It does not get you a maintained one.

Which ladder, and where Scorecard fits

Most people who have heard of any of this are thinking of OpenSSF Scorecard, which is a different tool: it scans your repository and gives you a score out of ten without asking you anything.

I picked ten projects to see how far apart the two can get, so read this as an existence proof rather than a correlation:

project	badge	badge updated	Scorecard	scanned
curl/curl	gold	2026-05-13	6.9	2022-11-09
kubernetes/kubernetes	passing	2017-08-16	7.6	2026-07-27
rails/rails	in progress, 94%	2020-10-15	6.3	2026-07-27
nodejs/node	passing	2024-05-07	6.1	2026-07-31
facebook/react	in progress, 81%	2018-02-19	7.0	2026-07-27
ossf/best-practices-badge	gold	2026-07-18	8.0	2026-07-31
ossf/scorecard	passing	2023-09-19	8.7	2026-07-25
thephpleague/commonmark	gold	2019-06-20	5.1	2026-07-27
daurnimator/lua-http	passing	2018-08-26	2.7	2026-07-27
FoveaCentral/google_maps_geocoder	passing	2024-11-12	8.4	2026-07-30

Scorecard last looked at curl in November 2022 and re-scanned most of the others this week.

commonmark holds gold on every tier and scores 5.1. React has no badge worth speaking of and scores 7.0. The disagreement runs both ways, which is the point.

The two tools are not independent: Scorecard includes your badge as one of its own checks. It fetches bestpractices.dev directly. But it is a low-weighted check, and removing it entirely moved these ten scores by between 0.0 and 0.3.

The clearest writing I found on either tool is the maintainers' own comparison, which concedes both sides:

Scorecards: This is entirely automated. Pros: You can evaluate any OSS project with it, immediately. Cons: It focuses on what can be automatically measured (not necessarily what's important...)

Best practices badge: this requires projects to fill in a form. Pros: It tries to focus on what's important (not what's easily automated); it can handle arbitrary situations & hosting platforms. Cons: It requires projects to work with it.

Scorecard can tell you whether branch protection is on, which no questionnaire can verify. The badge can ask whether you fix medium-severity vulnerabilities within 60 days, which no scanner can observe. Scorecard also re-runs itself, in principle: its published data for curl is from November 2022, so automated is not the same as current either.

If you are starting today: the metal ladder if you want the full interrogation, Baseline if you want the MUST-only subset that foundations are beginning to reference. FINOS already mandates Baseline rather than the metal ladder.

The Ruby corner

I went looking for my own ecosystem and it is thin. 105 entries list Ruby as their primary language: 1 gold, 1 silver, 18 passing, 85 still in progress.

The single Ruby gold is BadgeApp, the badge site itself. A Rails application, it holds gold on every tier including all three Baseline levels, and it is the only Ruby project on that list I would call well known.

Rails opened an entry in November 2015. It sits at 94%, has never earned the badge, and was last touched in October 2020. Ruby itself sits at 16%, edited exactly once, the day after the entry was created.

No entry at all for rubygems, rspec, rubocop, sidekiq, puma, devise, jekyll, rack, sinatra, hanami, or anything under hotwired. If you maintain a Ruby library and want a genuinely uncrowded thing to do this weekend, there it is.

Does any of it make software safer?

No study has measured badge status against security outcomes, and I went looking through the obvious places: Scholar, arXiv, the OpenSSF's own writing, and the foundation reports that track this sort of thing. The paper people reach for studies OpenSSF Scorecard rather than the badge, on 2,422 npm and PyPI packages, and its headline finding points the opposite way from how it gets summarised: vulnerability counts went up as the aggregate security score went up, at an R-squared of 0.04. There is a paper often cited as an independent study of the badge criteria. It turns out to be the text of a 2016 LWN article.

Only 16 of the 67 passing criteria are security criteria. The rest are about whether the project is run in a way a stranger can participate in.

So: the badge measures whether you did a specific set of sensible things once. Whether that makes your software safer is an open question that ten years of data has not been pointed at.

How to read one, and whether to get one

Read the date before you read the level. It is on the project page, and the badge image will never tell you.

You can check any project in one line:

curl -sL 'https://www.bestpractices.dev/projects.json?url=https://github.com/kubernetes/kubernetes' \
  | jq -r '.[] | "\(.name): \(.badge_level), last updated \(.updated_at[0:10])"'

Kubernetes: passing, last updated 2017-08-16

The -L matters: the API redirects to a URL-encoded form of your query, and without it you get an empty response and no error.

Two readers should skip it. If you want a signal that a project is healthy today, this is not that, and nothing on the site is. And if you are alone on your project, know where the ceiling is before you spend the day: silver costs you a written justification, and gold is closed to you outright. The Baseline ladder has no such gate, which is one practical reason to prefer it.

For everyone else, the honest case for filling one in is not the image. It is the questions. Ten years of public argument went into choosing them, the first pull request against them was from Greg Kroah-Hartman, and answering them costs a day if you go by the one maintainer who timed it. The badge at the end is a receipt for that day and nothing more.

Which is fine, as long as you read it as one.

Just put the re-check in your own calendar. The site will not send you one.

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!