SXN Labs

Turbo doesn't have three tools, it has three scopes

2026-08-06T09:00:00+02:00

Turbo’s documentation has a reputation for being incomplete. It isn’t, not really: every page says roughly what it should say. The problem is elsewhere. Drive, Frames and Streams are documented side by side, as three separate products, with nothing saying what connects them or how to choose. You learn the syntax of each one, and you stay stuck on the only question that matters when you sit down to write: which one, here, now.

There is an answer, and it is simple. Turbo does exactly one thing: it intercepts a navigation, fetches HTML, and replaces a portion of the document. Drive, Frames and Streams are not three mechanisms, they are three scopes of that replacement: the whole page, a named fragment, or any set of elements. And each scope answers the question that governs everything else: who decides the target, the client or the server.

What follows is what I wish I had read three years ago. It is long, it is meant to be reread in pieces, and it ends with an index that starts from the observable symptom. The reference versions are Turbo 8.0.23 and turbo-rails 2.0.23, both released on January 29, 2026, on Rails 8.

What's inside

The model in one pagethe three scopes, and who designates the target
Turbo Drivewhat is intercepted, the lifecycle, the cache, the config
Turbo Framesthe identifier rule, the layout, the attributes that matter
Turbo Streamsthe two worlds, the controller-to-view path, the eight actions
The HTTP status, and why 422
Morphingwhat it removes, idiomorph, the pantry, field values
Broadcaststhe macros, the request-id, the debounce, stream security
Stimulus and third-party libraries
Network and offlinefetch failures, service workers, Action Cable
The decision treewhich tool for which need
The symptom indexyou have a bug, you start here
What changed recently

If you are here because something is broken, go straight to item 11 and work your way back up to the relevant section.

The model in one page

The same mechanism, three scopes. What changes from one column to the next: the extent of the replacement, and who designates its target.

With Drive, the target is implicit: it is the <body>. The client decides to navigate, the server responds with a page, Turbo swaps the body and merges the head.

With Frames, the target is decided by the client before the request even leaves. The emitting frame puts its identifier in a Turbo-Frame header, and Turbo will accept from the response only the element carrying that same identifier. The server chooses nothing: it is subject to a constraint.

With Streams, the target is written into the response. The server says replace the element with this id, append this to the end of that one, remove that other one. It can aim at several places, not contiguous, and it can do so without anyone having asked for anything, over a WebSocket.

Everything else follows from that. A frame that does not update is almost always an identifier that does not match. A stream that has no effect is almost always a target missing from the DOM. Morphing, which we will get to, does not change this model: it only changes how the replacement is applied, not who decides it.

Turbo Drive

Drive is active as soon as you load @hotwired/turbo. There is nothing to write to benefit from it and, contrary to what the order of the documentation’s chapters suggests, that is where the majority of needs should stop.

What is intercepted, and what is not

Drive intercepts clicks on same-origin <a href> elements and form submissions. It does not intercept: links with a target attribute other than _self, download links, cross-origin URLs, and URLs whose extension appears in Turbo.config.drive.unvisitableExtensions (about fifty extensions, including .pdf, .zip, .csv, .jpg). That last list is configurable and is documented nowhere on the official site.

You switch it off case by case with data-turbo="false" on the element or any of its ancestors. A data-turbo="true" nested further down turns it back on.

The lifecycle

The dashed boxes are not events: they are the internal steps the events bracket.

Two points are worth stopping on, because they explain a good half of all lifecycle bugs.

The snapshot is taken of the page you are leaving, not the one you are loading. turbo:before-cache fires on the live document, right before Turbo makes a cloneNode(true) of it. So this is your last chance to undo what your JavaScript added to the DOM. And there is a cruel asymmetry: the clone loses the listeners but keeps the injected DOM. That is exactly the recipe for the library initialized twice on back navigation, which we will get to.

Useful detail: the clone also restores the selection of <select> elements (which cloneNode loses), clears the value of every input[type=password], and removes <noscript> elements.

A preview from the cache fires turbo:render twice. If the target URL is in the cache, Turbo displays the snapshot immediately while the network request runs. During that preview, <html> carries the data-turbo-preview attribute. That is how you test for it in a Stimulus controller:

connect() {
  if (document.documentElement.hasAttribute("data-turbo-preview")) return
  this.initExpensiveWidget()
}

The cache, in numbers

The Drive cache is an LRU of ten snapshots, in memory, in the tab. No localStorage, no IndexedDB, no Cache API. It dies when the tab closes, on reload, and it is emptied in full on every unsafe form submission. It contains only HTML: no stylesheet, no image, no script.

Remember the phrasing: Turbo’s cache is a perceived-latency optimization, it is not a persistence layer. It gives you strictly nothing offline.

Three levers:

What you want	How
Never cache this page	`<meta name="turbo-cache-control" content="no-cache">`
Cache it but never show it as a preview	`<meta name="turbo-cache-control" content="no-preview">`
Remove an element before caching	`data-turbo-temporary` on the element

data-turbo-cache="false" was removed in 8.0.21, in January 2026, after three years of deprecation. So was Turbo.clearCache(), replaced by Turbo.cache.clear(). Both still linger in a pile of blog posts, and in Stack Overflow answers, that site where humans used to write documentation for one another.

Turbo.config

Since 8.0.6, configuration goes through a single object. The old setter functions (setProgressBarDelay, setConfirmMethod, setFormMode) still exist but emit a console warning.

Turbo.config.drive.progressBarDelay = 500          // ms before the progress bar
Turbo.config.drive.enabled          = true
Turbo.config.forms.mode             = "on"         // on | off | optin
Turbo.config.forms.submitter        = "disabled"   // disabled | aria-disabled
Turbo.config.forms.confirm          = async (message) => { /* Promise<boolean> */ }

forms.submitter deserves a word, because it is a case where Turbo’s default is bad for accessibility. By default, Turbo sets the disabled attribute on the button during submission. A disabled button stays exposed in the accessibility tree, but it loses its focusability and its place in the tab order: focus falls back to <body>, and someone navigating by keyboard or screen reader loses their position on every form submission. With "aria-disabled", Turbo sets aria-disabled="true" and cancels click events on the button: the protection against double submission is identical, but the control stays focusable.

Turbo.config.forms.submitter = "aria-disabled"

One line, in application.js. There is no reason not to write it.

Prefetching

Since Turbo 8, prefetch on hover is on by default. Turbo waits 100 ms after mouseenter, sends a GET with the X-Sec-Purpose: prefetch header, and keeps the response in a single-entry cache for 10 seconds.

That means moving the mouse over a link fires a request against your server. If your GET actions are not idempotent, or if your server does not like free traffic, switch it off:

<meta name="turbo-prefetch" content="false">     <%# global %>
<a href="/x" data-turbo-prefetch="false">…</a>   <%# per element %>

Not to be confused with data-turbo-preload, which is a different mechanism, a different cache, and a load on DOMContentLoaded rather than on hover.

Turbo Frames

It all comes down to one identifier

Turbo does exactly one thing with the response: it looks for a <turbo-frame> with the same id. Everything else is discarded.

The matching rule, literally, is container.querySelector("turbo-frame#" + CSS.escape(id)). No fuzzy matching, no configurable selector. That is why the most robust pattern is to let the server echo back the identifier it was sent, through turbo-rails’ turbo_frame_request_id helper:

<%= turbo_frame_tag turbo_frame_request_id || "invoice_detail" do %>
  …
<% end %>

The fallback is not decorative: on a full-page visit the header is absent and turbo_frame_tag nil produces id="", which silently breaks every later navigation to that frame.

There is a second chance, rarely used: the recurse attribute. If no frame with the same id is found but a <turbo-frame src recurse~="my-id"> is present, Turbo waits for it to load and then looks inside it.

And if nothing matches, the sequence is this:

complete is set on the frame, before the event.
turbo:frame-missing is dispatched on the frame, cancelable, with detail.response (a raw Response) and detail.visit(urlOrResponse, options).
If nobody cancels, the frame displays <strong class="turbo-frame-error">Content missing</strong> and Turbo throws a TurboFrameMissingError.

The most frequent case is session expiry: the request leaves from the frame, the server redirects to /login, and the login page obviously does not contain your frame. The right answer is not to handle the event, it is to mark the login page:

<%= turbo_page_requires_reload %>

which emits <meta name="turbo-visit-control" content="reload">. Turbo then skips frame extraction entirely and performs a full-page visit. That is the intended escape hatch, and it is far better than a global turbo:frame-missing listener.

A trap while we are here, and it applies to turbo_refreshes_with further down too: this helper calls provide :head. It writes nothing at the call site, despite the <%= %>. Without <%= yield :head %> in your layout, the meta tag never comes out and nothing happens. The turbo_page_requires_reload_tag variant renders the tag in place if you prefer to position it yourself.

The layout, and the static layout trap

turbo-rails installs this into ActionController::Base:

layout -> { "turbo_rails/frame" if turbo_frame_request? }
etag   { :frame if turbo_frame_request? }

The turbo_rails/frame layout is minimal (just csrf_meta_tags and yield :head), not absent, so that content_for :head and CSRF keep working.

The trap: if you write layout "admin" in a controller, you overwrite that lambda. Frame requests will then render the full layout. It still works, because Turbo extracts the frame anyway, but you pay for the entire layout on every frame request, and all the JavaScript injected into the <head> is re-evaluated. You have to convert the declaration into a method:

layout :layout_for_request

private

def layout_for_request
  turbo_frame_request? ? "turbo_rails/frame" : "admin"
end

No error, no warning. Just a silent bill.

The attributes that matter

Attribute	Effect
`src`	Loads this URL into the frame. Passed through `url_for`, so a model works.
`loading="lazy"`	Loads only on entry into the viewport, via an `IntersectionObserver`.
`target`	Default target for descendant links and forms.
`data-turbo-frame`	On a link, a form or a submit button. Overrides `target`. The button wins over the form.
`_top`	Breaks out of the frame: Drive treats the navigation as a full-page visit.
`_parent`	Targets the nearest ancestor frame. Added in 8.0.21.
`busy`	Set by Turbo during loading, along with `aria-busy="true"`. Useful in CSS.
`complete`	Set after a successful render. Careful: the JS property `frame.complete` does not read this attribute.
`disabled`	Cancels the in-flight request and ignores any navigation.
`autoscroll`	Scrolls to the frame after rendering. `data-autoscroll-block` defaults to `end`, not `start`.
`refresh="morph"`	With `src`, the frame is reloaded rather than morphed during a page morph.

Two behaviors that often surprise people:

A frame renders 4xx and 5xx exactly like 2xx. The status code is not consulted at all. Only two things can divert the response: a non-HTML Content-Type, in which case loadResponse does nothing at all, with no event and no error, and the turbo-visit-control: reload seen above, which triggers a full-page visit with a console warning.

A form inside a frame does not need to redirect. The “form responses must redirect” constraint only applies to full-page submissions. A 200 OK with HTML is perfectly valid inside a frame.

Turbo Streams

A <turbo-stream> is an envelope. It carries an action, a target, and a <template>:

<turbo-stream action="replace" target="invoice_42">
  <template><div id="invoice_42">…</div></template>
</turbo-stream>

There are two worlds behind this format, and conflating them is the number one source of confusion.

The first world is an HTTP response: the user does something, the server responds with text/vnd.turbo-stream.html, the tab applies it. It is synchronous, it lives in the request context, current_user exists.

The second is a broadcast: a model publishes on an Action Cable channel, every subscribed tab receives it. It is asynchronous, it runs in a job, there is no request, no session, no current_user. We come back to it below, because that is where the real problems hide.

If you knew Rails before 2021, the first world will ring a bell. Answering a submission with a document that describes DOM mutations is exactly what create.js.erb did back in the UJS days. The difference comes down to two points, and they are decisive: the server returns HTML instead of returning JavaScript to evaluate, and the mutation vocabulary is closed at eight actions instead of being “everything jQuery knows how to do”. We lost freedom and gained a zero attack surface, an HTTP cache that works, and responses you can read.

The full path, from controller to view

Here is the canonical server-side form, the one you write in 90% of cases.

# app/controllers/invoices_controller.rb
def create
  @invoice = Invoice.new(invoice_params)

  if @invoice.save
    respond_to do |format|
      format.turbo_stream                                    # -> create.turbo_stream.erb
      format.html { redirect_to @invoice, status: :see_other }
    end
  else
    respond_to do |format|
      format.turbo_stream do
        render turbo_stream: turbo_stream.replace(
          "invoice_form", partial: "invoices/form", locals: { invoice: @invoice }
        ), status: :unprocessable_entity
      end
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end

Two ways to respond, and you should choose knowingly. The bare format.turbo_stream renders a template, which is the right choice as soon as several zones change. The inline render turbo_stream: renders a single action and saves a file, which is the right choice when there really is only one.

The template itself is a plain ERB file that yields the builder:

<%# app/views/invoices/create.turbo_stream.erb %>
<%= turbo_stream.prepend "invoices", @invoice %>
<%= turbo_stream.update "invoices_count", Invoice.count %>
<%= turbo_stream.replace "invoice_form" do %>
  <%= render "invoices/form", invoice: Invoice.new %>
<% end %>

Three remarks on those three lines, because they condense almost the whole API.

turbo_stream.prepend "invoices", @invoice takes no partial: passing a record is enough, the builder calls to_partial_path and renders invoices/_invoice.html.erb. That is also why this partial must render an element with id="<%= dom_id(invoice) %>", without which nothing will be able to target it afterwards.

turbo_stream.update accepts a raw string as content, which saves a one-line partial for a counter.

The block form captures whatever you write inside it. Handy, but it is also the one place where it is easy to forget that the content is rendered outside the page context, so without the ivars set by some other before_action.

And on the calling view side, the rule is the same as everywhere: what the stream aims at must exist with the right id.

<%# app/views/invoices/index.html.erb %>
<div id="invoices_count"><%= @invoices.count %></div>

<div id="invoices">
  <%= render @invoices %>
</div>

<div id="invoice_form">
  <%= render "invoices/form", invoice: Invoice.new %>
</div>

<%# app/views/invoices/_invoice.html.erb %>
<div id="<%= dom_id(invoice) %>" class="invoice">
  <%= invoice.reference %>
  <%= button_to "Supprimer", invoice, method: :delete, form: { data: { turbo_confirm: "Sûr ?" } } %>
</div>

Note data-turbo-confirm on the button_to form, the direct successor to rails-ujs’ data-confirm. The difference is that it is pluggable: Turbo.config.forms.confirm accepts your own function, which finally lets you replace the native dialog with your own modal without rewriting the mechanism.

Eight actions, and `morph` is not one of them

This is the most widespread mistake in the whole ecosystem, including in widely read blog posts.

Action	What it does	Target required
`append`	Adds to the end of the target’s content	✓
`prepend`	Adds at the beginning	✓
`before`	Inserts before the target	✓
`after`	Inserts after the target	✓
`replace`	Replaces the target itself	✓
`update`	Replaces the target’s content	✓
`remove`	Removes the target. No `<template>`	✓
`refresh`	Triggers a page refresh. No `<template>`	✕

That is all. There is no morph action. Morphing is an attribute, method="morph", and among the targeted actions only replace and update read it. Writing turbo_stream.append("x", method: :morph) does produce the attribute in the HTML, and the JavaScript handler for append ignores it purely and simply. refresh reads method too, but for another reason: to choose the render mode of the page refresh there, broadcast by broadcast.

Two barely documented behaviors:

append and prepend deduplicate: if a direct child of the target carries the same id as a top-level incoming element, the old one is removed. append therefore behaves like an upsert, which is very handy and never stated. Since 8.0.21, before and after do the same thing on the target’s siblings.

refresh can be deduplicated through a request-id attribute, the subject of the broadcasts section.

`target` and `targets` are not the same thing

turbo_stream.replace     "invoice_42"        # target  => getElementById
turbo_stream.replace_all ".invoice-row"      # targets => querySelectorAll

target takes a bare DOM id, not a selector, and resolves to at most one element. targets takes a CSS selector and applies the action to every match. If both are present, target wins.

On the Ruby side, this difference in kind is absorbed for you. If you pass a record rather than a string, the helper puts the hash in the right place:

turbo_stream.replace     @invoice   # target="invoice_42"    <- bare dom_id
turbo_stream.replace_all @invoice   # targets="#invoice_42"  <- dom_id with the #

So the trap only shows up the day you write the selector by hand, because at that point nobody is correcting it any more: turbo_stream.replace_all "invoice-row" without the dot or the hash matches nothing, and says nothing.

The silence when the target does not exist

This is the most expensive behavior in all of Turbo in debugging time.

If document.getElementById(target) returns null, the getter returns an empty array, and every action iterates over that empty array. No warning, at any log level. The stream arrives, it is visible in the Network tab, it is visible in the Rails logs, and nothing happens.

The classic causes: a misspelled or accidentally pluralized dom_id, a target living inside a <template> or an <iframe> (explicitly unsupported), or a target inside a loading="lazy" frame that has not loaded yet.

There is a second silent variant, sneakier: on a GET request, Turbo sends the Accept: text/vnd.turbo-stream.html header only if the link or the form carries data-turbo-stream. Without that attribute, your respond_to will never see the turbo_stream format and will fall into the HTML branch.

Adding your own actions

The mechanism is simpler than it looks and it is a good investment as soon as you catch yourself stacking streams to express a single intention.

On the Ruby side, a load hook:

# config/initializers/turbo.rb
ActiveSupport.on_load :turbo_streams_tag_builder do
  def highlight(target)       = action     :highlight, target
  def highlight_all(targets)  = action_all :highlight, targets
end

On the JavaScript side, an entry in Turbo.StreamActions, where this is the <turbo-stream> element:

Turbo.StreamActions.highlight = function () {
  this.targetElements.forEach((el) => {
    el.animate([{ backgroundColor: "#FFD83F" }, { backgroundColor: "transparent" }],
               { duration: 1200 })
  })
}

And from a model, without going through the builder:

after_update_commit -> {
  broadcast_action_to "plannings", action: :highlight, target: "gantt", html: ""
}

If the action is not registered on the JavaScript side, the element throws unknown action. It is one of the rare places where Turbo is loud.

The HTTP status, and why 422

Three questions, in this order. The HTTP status is consulted last, and only for a full-page navigation.

The number one symptom in all of Hotwire comes down to one line of Turbo’s code:

responseSucceededWithoutRedirect(response) {
  return response.statusCode == 200 && !response.redirected
}

If you answer a POST with 200 and HTML and no redirect, Turbo prints console.error("Form responses must redirect to another location") and renders nothing. The page looks frozen. The form went out, the progress bar ran all the way, and the error messages never appeared.

The reason is given in the manual, and it is a good one: browsers have native behavior for reloading a page that came from a POST, that “do you want to resubmit the form?” dialog, which Turbo cannot reproduce. Rather than lie about the URL, it refuses.

Hence the Rails convention, which the scaffold generator already applies:

render :new, status: :unprocessable_entity  # 422: the response is rendered, the URL does not move
redirect_to @invoice, status: :see_other    # 303: after update and destroy

The 303 is not a Rails whim, it is a consequence of the Fetch specification. Turbo passes redirect: "follow" and lets the browser follow. And:

303 always forces the switch to GET.
301 and 302 force the switch to GET only for POST. A DELETE redirected with a 302 is replayed as a DELETE on the target URL.
307 and 308 always preserve the method.

So a redirect_to invoices_path after a destroy without status: :see_other sends a DELETE /invoices to your server. At best a routing error, at worst something you had not planned for.

One nuance that makes life easier: a turbo-stream response short-circuits all of this. Turbo intercepts on the Content-Type before it even looks at the status. render turbo_stream: …, status: :unprocessable_entity works perfectly, and the 422 now only serves your tests and non-Turbo clients.

A small amusing detail: the test is on statusCode == 200 exactly. A 201 Created goes straight through the guard and carries on to a visit.

Morphing

Turbo 8 introduced page refreshes with morphing. The idea: rather than replacing the <body>, compare the old tree with the new one, and change only what differs. You keep the scroll, the focus, the text selection, the state of CSS transitions.

You turn it on in two lines, in the layout:

<%= turbo_refreshes_with method: :morph, scroll: :preserve %>

And here is the first trap, responsible for a good share of the “morphing does not work for me” reports: turbo_refreshes_with calls provide :head. It writes nothing where you call it. Without <%= yield :head %> in your layout, the meta tags never come out, and Turbo keeps doing classic replacements, without reporting anything. The accepted values are :replace or :morph for method:, :reset or :preserve for scroll:, anything else raises an ArgumentError.

What actually triggers a morph

A morph only happens for a page refresh, and the exact condition comes down to two clauses: same pathname (the query string and the fragment do not count) and action === "replace".

In practice, for a form, that amounts to “same URL”, because Turbo only picks replace if the destination URL is strictly identical to the starting URL. A POST /invoices/42 that redirects to /invoices/42 morphs. A POST /invoices/42/edit that redirects to /invoices/42 does not morph: two different paths, classic rendering.

But the action clause counts for the rest. A data-turbo-action="replace" link from /invoices?page=2 to /invoices?page=3 morphs too, since the pathname is the same.

The two most common triggers: a form that redirects to the same URL, and a <turbo-stream action="refresh"> broadcast.

What morphing removes

Same beginning, same end. It is the middle that changes, and the middle is where your code lives.

Three corrections to some very widespread folklore:

turbo:load does fire after a morph. A refresh is a real visit. What does not replay is the inline <script> tags.

turbo:before-cache no longer fires. The refresh passes shouldCacheSnapshot: false. And turbo:before-cache is the global teardown point recommended everywhere since Turbolinks. Turning morphing on therefore silently disables the cleanup code of half the existing Rails applications.

Scripts are not “never re-executed”, they are re-executed if they are new. idiomorph matches the old <script> with the new one by tag name, then syncs the text content with oldNode.nodeValue = newNode.nodeValue. Assigning nodeValue on an already executed script never re-executes it. A genuinely new script, on the other hand, with no partner in the old tree, is inserted and runs.

idiomorph decides by identifiers

An id is considered stable only if all three of the following conditions hold: it exists in both trees, the tag name is identical, and it is duplicated in neither of them.

That third condition deserves a box around it. A single duplicated id anywhere in the document takes that id out of the set of persistent identifiers, in both copies. Matching then falls back to position. So an accidental duplicate in a partial degrades the morphing of elements that have nothing to do with it.

Without stable identifiers, everything is paired by position. Adding a row at the top of a list rewrites the text of every row rather than inserting a node. Consequences: CSS transitions restart everywhere, and any client state carried by a row (an open menu, a checked box, a playing video) shifts by one.

The rule is short: give every list item a stable, unique id, never reuse it, never change the associated tag. dom_id(record) does exactly that.

The pantry, and why it breaks in Safari

Here is the mechanism that explains the “it works on my machine but not on his” bug reports, and that is documented nowhere.

When a node with a persistent identifier has to change place, idiomorph does not clone it. It moves it into a hidden <div> inserted after </body>, the pantry, then puts it back in position later. The move uses parentNode.moveBefore() if the browser provides it, otherwise insertBefore.

This is not an implementation detail, it is a fork in behavior:

With moveBefore (Chromium 133 and up, Firefox 144 and up), the node stays connected. No Stimulus disconnect/connect, <iframe> elements do not reload, a <video> keeps playing.
With insertBefore, the node is disconnected then reconnected. disconnect() then connect() are called, <iframe> elements reload, video playback restarts from zero, CSS transitions restart, and the connectedCallback of custom elements replays.

As of this writing, the insertBefore camp has shrunk to Safari and WebKit iOS, plus versions earlier than Chrome 133 and Firefox 144. So yes, a morphing bug can be perfectly reproducible in Safari and nowhere to be found in Chrome. It is not your code.

Field values are not protected

idiomorph does not only sync attributes, it also writes the live DOM properties of form controls. The code is explicit:

if (!newElement.hasAttribute("value")) {
  if (!ignoreAttribute("value", oldElement, "remove", ctx)) {
    oldElement.value = ""           // what the user had typed
    oldElement.removeAttribute("value")
  }
}

And a server-rendered <input type="text"> normally has no value attribute. So a refresh that arrives while someone is typing erases what they are typing. Same treatment for checked, disabled, <option selected> and the content of <textarea> elements.

idiomorph has an ignoreActiveValue option that excludes document.activeElement from this synchronization. Turbo does not enable it, and does not expose it anywhere: you cannot set it.

So it is on you to protect the field yourself, and the only lever available on the Turbo side is data-turbo-permanent, which skips the morph on the element. Since you do not want to freeze the field permanently, you set it on focus and remove it on the way out. This snippet comes from Turbo’s own test fixtures, which makes it the most official answer in existence:

addEventListener("focusin", ({ target }) => {
  if (target instanceof HTMLInputElement && !target.hasAttribute("data-turbo-permanent")) {
    target.toggleAttribute("data-turbo-permanent", true)
    target.addEventListener("focusout", () => {
      target.toggleAttribute("data-turbo-permanent", false)
    }, { once: true })
  }
})

On focus, more precisely: idiomorph restores focus, but only for an <input> or a <textarea> that carries an id. A focused <select>, a focused contenteditable or a field without an id lose focus, and there is no option to change that.

And autofocus is not honored at all under morph: MorphingPageRenderer declares shouldAutofocus as false.

The protection toolbox

From the finest to the most brutal:

// 1. Protect one specific attribute
document.addEventListener("turbo:before-morph-attribute", (event) => {
  const { attributeName } = event.detail            // + mutationType: "update" | "remove"
  if (attributeName === "open") event.preventDefault()
})

// 2. Protect an entire subtree
document.addEventListener("turbo:before-morph-element", (event) => {
  if (event.target.matches(".widget-tiers")) event.preventDefault()
})

// 3. Reinitialize afterwards (turbo:morph-element)
document.addEventListener("turbo:morph-element", ({ target }) => { /* … */ })

<%# 4. The complete freeze %>
<div id="carte" data-turbo-permanent>…</div>

Two clarifications the documentation does not give.

data-turbo-permanent does not have the same semantics depending on the render mode. In classic rendering, the selector is [id][data-turbo-permanent]: the id is mandatory, and the live node is transplanted into the new body. Under morph, only the attribute is tested, the id is not required, and the node is simply skipped. The id becomes necessary again for added nodes, where it serves for deduplication.

Under morph, data-turbo-permanent freezes the subtree completely. Legitimate server updates inside it will never arrive. It is the tool of last resort, not the reflex.

Finally, turbo:before-morph-element is also dispatched for nodes about to be removed, and in that case detail.newElement is undefined. A listener that writes event.detail.newElement.matches(…) will throw a TypeError sooner or later.

Broadcasts

This is where the mental model needs to be soundest, because the code is written in one line and the problems show up in production.

Four macros, and one asymmetry

class Card < ApplicationRecord
  broadcasts_refreshes_to :board   # a single after_commit, everything goes to board
end

Macro	Create	Update	Destroy
`broadcasts_to :board`	`append` to `board`	`replace` to `board`	`remove` to `board`
`broadcasts`	`append` to `"cards"`	`replace` to the record’s GID stream	`remove` to the GID stream
`broadcasts_refreshes`	`refresh` to `"cards"`	`refresh` to the GID stream	`refresh` to the GID stream
`broadcasts_refreshes_to :board`	`refresh` to `board`	`refresh` to `board`	`refresh` to `board`

Read the second and third rows twice. broadcasts and broadcasts_refreshes send creates to the collection stream, but updates and destroys to the record’s own stream. A page that only does turbo_stream_from "cards" will see the new cards appear and will never see the updates or the deletions.

This is intentional: the intended pattern is turbo_stream_from Card on the index and turbo_stream_from @card on the detail page. But it is written nowhere in readable form. If you want all three events to go to the same place, the macro to use is broadcasts_refreshes_to, which installs a single after_commit.

Another asymmetry worth knowing: for the first three macros, deletions are synchronous while creates and updates go through a job. That is logical (a deletion has nothing to render), but it means the deletion is not debounced. broadcasts_refreshes_to escapes this precisely because it installs only one after_commit: everything there is asynchronous and debounced, including the destroy.

The full path of a refresh

The tab that writes receives its own broadcast. The whole identifier mechanism exists to let it ignore that broadcast.

Every Turbo fetch generates a UUID, adds it to a set capped at 20 entries, and sends it as X-Turbo-Request-Id. On the Rails side, an around_action copies it into Turbo.current_request_id. The broadcast re-emits it in the request-id attribute. On reception, Session#refresh ignores the refresh if the identifier is in its local set.

The reason is a good one: the tab that wrote has already displayed the result of its request. Replaying the refresh would cost a pointless round trip, the scroll position and the focus.

Four ways to lose this protection, all verifiable in the code:

broadcast_refresh_to, the synchronous variant, transmits no request_id. Only the _later_ variant does. It is also the variant the macro installs for destroy.
From a background job, Turbo.current_request_id is nil: it is a thread_mattr_accessor set by an around_action. Every tab refreshes, including the one that started it. That is generally what you want.
The set is capped at 20. More than 20 Turbo requests between the send and the arrival of the broadcast and the identifier is evicted. With prefetch on hover on by default, that is no longer so theoretical.
turbo_stream.refresh rendered as a direct response to a request carries that request’s identifier by default, so the requesting tab ignores it. You have to write turbo_stream.refresh(request_id: nil).

The debounce, and what it costs

broadcast_refresh_later_to goes through a Turbo::ThreadDebouncer memoized in Thread.current, keyed on (stream name, request_id), which schedules a Concurrent::ScheduledTask 0.5 seconds into the future. Each new call cancels the previous one. A thousand records modified in one request therefore give one broadcast.

On the client side, Session#refresh is debounced at 150 ms on top of that.

Two less pleasant consequences:

In a short-lived process, the broadcast is never sent. A rails runner, a rake task, a container that exits after its work: the process ends before the scheduled task fires. No error. The documented workaround is a sleep Turbo::Debouncer::DEFAULT_DELAY + 0.1.

In tests, there is no debounce at all. turbo-rails installs a Turbo::ImmediateDebouncer in the test environment. Your assertions count N broadcasts, production will see 1.

`current_user` does not exist in a broadcast

Every asynchronous broadcast renders its partial through:

ApplicationController.render(formats: [format], **rendering)

That is, an ActionController::Renderer with a synthetic Rack environment. There is no session, no cookies, no Warden key. Mechanical consequences:

current_user is nil. Devise returns nil rather than raising: a partial that hides an admin button behind if current_user.admin? therefore renders the non-admin branch for everyone, silently, with nothing in the console or in the logs.
Current.* attributes are empty, for the same reason.
ApplicationController is hard-coded. No prepend_view_path, no ivars set by a before_action, no helpers from another controller.
_url helpers raise Missing host to link to! on Rails 7.1 and later, because the renderer’s defaults no longer include an http_host. The _path helpers work.

The pattern that scales is the only one that accepts that the broadcast HTML is the same for every recipient: broadcast a neutral partial, and have the personalized parts loaded by a frame, which each browser will go and fetch with its own cookies.

<%# the broadcast partial, identical for everyone %>
<div id="<%= dom_id(card) %>">
  <%= card.title %>
  <%= turbo_frame_tag "#{dom_id(card)}_actions", src: card_actions_path(card), loading: :lazy %>
</div>

The alternatives: broadcast one stream per user, which is correct but O(users), or explicitly pass everything you need through locals: and treat “this partial is broadcastable” as a strict property of the partial.

It is also, incidentally, the best argument in favor of broadcasts_refreshes: a refresh renders nothing on the server. Each browser makes its own request, with its own session. The problem disappears by construction.

A signed stream is not an authorized stream

<%= turbo_stream_from "quotes" %>

This line produces a signed-stream-name that is identical for every user. The signature prevents forgery, not reading: the name is a MessageVerifier, so signed base64, not encrypted. Two base64 -d calls separate your page source from the string gid://app/Account/5, and nobody needs your key to run them.

And Turbo::StreamsChannel#subscribed accepts the subscription with no additional check whatsoever. It verifies that the signature is valid, full stop. Anyone holding a valid signed name can subscribe, including a former employee whose access you revoked, indefinitely: these names do not expire.

So you have to carry the scope in the stream name:

broadcasts_refreshes_to ->(quote) { [quote.company, :quotes] }

<%= turbo_stream_from current_company, :quotes %>

And if you need real authorization, for example because membership can be revoked, you have to write your own channel and do the check before stream_from.

Two plumbing traps

In development, the default Action Cable adapter is async, single-process. A broadcast triggered from bin/rails console will never reach a browser connected to a separately started server. Switch to redis in config/cable.yml, or use <%= console %> to trigger it inside the same process.

turbo-rails’ jobs inherit from ActiveJob::Base, not from your ApplicationJob. Your retry policy, your queue and your callbacks do not apply. All three jobs do discard_on ActiveJob::DeserializationError: a record deleted between enqueue and execution makes the broadcast vanish, with no retry and no error.

Stimulus and third-party libraries

The lifecycle, precisely

Stimulus knows nothing about Turbo. It reacts to a MutationObserver, in the microtask that follows each modification.

On a classic visit, the order is: turbo:before-cache, then the <body> swap, so disconnect() on the old controllers and connect() on the new ones, then turbo:render and turbo:load. Note that disconnect() comes after turbo:before-cache: the snapshot is taken first. That is why turbo:before-cache was historically the right place to undo whatever a library had injected.

Under morph, there is neither turbo:before-cache nor disconnect/connect for elements modified in place. The callbacks only fire if the node is actually added or removed, if it is reparented through the pantry on the insertBefore path, or if the value of data-controller changes.

The recommended reconnection pattern comes, once again, from Turbo’s test fixtures:

addEventListener("turbo:morph-element", ({ target }) => {
  for (const { element, context } of application.controllers) {
    if (element === target) {
      context.disconnect()
      context.connect()
    }
  }
})

It is expensive on a large page, since it reconnects every controller of every morphed element, but it is the most official answer in existence.

What breaks, and why

The general rule: any library that injects DOM the server does not render, or that writes class or style at runtime, is incompatible with morphing without explicit protection.

Library	What breaks	The cause	The fix
Chart.js, Chartkick	The chart disappears, a “Loading…” stays behind	Chartkick listens for `turbo:before-render` and destroys every chart, including when `renderMethod` is `morph`. The `<script>` that would recreate it does not re-execute	`Chartkick.config.autoDestroy = false`, then redraw on `turbo:morph`
Alpine.js	Elements become invisible again, the `:class` bindings drop	Alpine removes `x-cloak` on init and writes `class` and `style.display` at runtime. The server HTML knows nothing about them, the morph puts them back	Cancel `turbo:before-morph-attribute` for `x-cloak`, `class` and `style` on `[x-data]` subtrees
Tom Select, Select2, Choices	The widget disappears, the selection reverts	The injected `<div>` is not in the server HTML, so it is removed. The original `<select>` survives, so there is no reconnection	`data-turbo-permanent` with an `id`, or destroy and reinitialize on `turbo:morph-element`
Leaflet, Mapbox GL	Dead map, gray tiles, or `Map container is already initialized`	The injected panes are removed, the container survives	`map.remove()` in `disconnect()`, `invalidateSize()` after reconnection
`<dialog>` opened with `showModal()`	The page becomes unusable	The morph rewrites the content but does not reset the browser’s top layer	Open, unresolved ticket. Close the dialog on `turbo:before-render`, or exclude it from the morph
`<details>`	Panels open or close on their own for every viewer	`open` is synced like an ordinary attribute	Cancel `turbo:before-morph-attribute` for `attributeName === "open"`
`<turbo-cable-stream-source>`	Broadcasts are lost	If it is reparented on the `insertBefore` path, it unsubscribes then resubscribes	Give it a stable `id` and move it out of reordered areas

Trix and Action Text have been fixed since March 2025, contrary to what many blog posts still claim. The technique used is worth knowing, because it is the best general pattern for a custom element under morph: <trix-editor> sets a connected attribute on initialization and declares it in observedAttributes. The server HTML does not contain it, so the morph removes it, attributeChangedCallback fires, and the element reinitializes itself.

It is a self-healing custom element. If you write your own, do that.

What leaks if you do not clean up

Turbo turns your application into a long-running process. Everything you create in connect() must be torn down in disconnect(), without exception: the setInterval timers, the addEventListener calls on window or document, the IntersectionObserver and ResizeObserver instances (which keep the observed node alive and block collection of the entire detached subtree), the Action Cable subscriptions, the Chart.js instances.

The case of WebGL contexts is worth citing: browsers cap them at around sixteen. One Mapbox map left undestroyed, sixteen navigations, and all your canvases go blank.

Injecting a stream without an HTTP response

Turbo.renderStreamMessage() accepts an HTML string containing <turbo-stream> elements and applies them as if they had arrived over the network. The <script> tags inside the <template> are activated, permanent elements are preserved, focus is restored by id.

This is what you need for: a transport other than Action Cable (raw WebSocket, SSE, postMessage from a service worker), an optimistic update synthesized on the client before the server confirms, or a native shell pushing HTML into the webview.

Turbo.renderStreamMessage(
  `<turbo-stream action="append" target="messages"><template>…</template></turbo-stream>`
)

Network and offline

When the request fails, nothing happens

Turbo dispatches turbo:fetch-request-error, which bubbles and crosses shadow roots, with detail.request and detail.error. A listener placed on document catches it reliably.

What happens next depends on the context, and the difference is brutal.

For a frame or a form submission, the user sees nothing. No banner, no toast. A console.error, and the frame stays on its old content.

For a Drive visit, Turbo reloads the page completely. The network failure is recorded as SystemStatusCode.networkFailure, the adapter dispatches turbo:reload with reason: "request_failed" and does window.location.href = …. Offline, that means: the browser’s network error page, and your application destroyed. It is the worst possible moment to lose client state.

That detail changes the nature of the listener below. The preventDefault() is not cosmetic: it makes Turbo’s internal guard return false, which short-circuits the error handling and therefore the reload.

document.addEventListener("turbo:fetch-request-error", (event) => {
  event.preventDefault()   // also prevents the full reload on a Drive visit
  showOfflineBanner(event.detail.error)
})
window.addEventListener("offline", () => showOfflineBanner())
window.addEventListener("online",  () => hideOfflineBanner())

Watch out for an ordering trap: turbo:before-fetch-response fires only if there is a response. Network-loss detection built on it will never fire when the network is actually down.

Turbo and service workers

Turbo navigations are window.fetch() calls. Turbo passes no mode option, so on the service worker side the request has mode === "cors" and, more surprisingly, destination === "", the default value for anything coming out of fetch().

A service worker that routes on request.mode === 'navigate' therefore misses every Drive navigation. And the fix you read everywhere, adding || request.destination === 'document', catches nothing at all: that destination only exists for navigations initiated by the browser itself. You have to discriminate on what Turbo actually sends:

const isDocumentNavigation = ({ request }) =>
  request.method === 'GET' && (
    request.mode === 'navigate' ||                                   // browser navigation
    (request.destination === '' &&                                   // Turbo's fetch()
     (request.headers.get('Accept') || '').includes('text/html'))
  )

registerRoute(isDocumentNavigation, new NetworkFirst())
registerRoute(
  ({ request }) => ['style', 'script', 'image', 'font'].includes(request.destination),
  new CacheFirst()
)

The second route works as is: those requests really are initiated by the browser and carry a populated destination.

Two ways to break Turbo from a service worker:

Serving a response with the wrong Content-Type. Turbo records contentTypeMismatch and abandons the visit silently.

Serving HTML whose asset fingerprints no longer match. Turbo compares the data-turbo-track="reload" elements between snapshots. On divergence, it triggers a full browser reload, which the service worker answers again from the cache. You have a reload loop.

Three constraints specific to Rails 8:

Put the service worker at a stable root URL. An asset digested by Propshaft cannot control a scope beyond its own directory, and its URL changes as soon as its content changes. Two options: public/service-worker.js, or the route Rails 8 generates, which is commented out by default in config/routes.rb and therefore has to be uncommented: get "service-worker" => "rails/pwa#service_worker", as: :pwa_service_worker. Note the rails/pwa controller and the path without .js.
Importmaps do not apply inside a service worker. There is no <script type="importmap"> in there. importScripts() or a classic worker with no imports.
Digested asset URLs change with their content. A precache list written by hand goes stale on the first deploy that touches a file. Prefer runtime caching, by request.destination.

An official patch is in progress (turbo#1427, a Turbo.offline API shipped in a separate bundle) but it is open, not merged. Do not write an architecture that depends on it.

Action Cable replays nothing

The only signal available is an attribute on an element. There is no event, no sequence number, no catch-up.

This is, in my view, the least documented production risk in all of Hotwire.

Action Cable is publish/subscribe with no persistence, no acknowledgement, no sequence number and no history. A message published while a consumer is disconnected is delivered to those who are subscribed at that instant, then thrown away. There is nothing in the protocol capable of replaying it.

Action Cable reconnects on its own, and the tab receives the subsequent messages again. Everything that went through during the outage is permanently lost. The page is then silently, indefinitely stale. No error, no indication, nothing.

Wifi switching over, a computer waking up, a tunnel, a deploy: this is not an edge case, it is the daily life of a mobile user.

The entire observation surface fits in one attribute: <turbo-cable-stream-source> sets and removes connected. No event is dispatched. Hence the workaround, which is application code:

// Stimulus controller placed on <turbo-cable-stream-source>
connect() {
  this.observer = new MutationObserver(() => {
    const isConnected = this.element.hasAttribute("connected")
    if (isConnected && this.wasDisconnected) {
      Turbo.visit(location.href, { action: "replace" })
    }
    this.wasDisconnected = !isConnected
  })
  this.observer.observe(this.element, { attributeFilter: ["connected"] })
}

disconnect() { this.observer.disconnect() }

Handle visibilitychange (the machine waking up) and window.online too.

With turbo_refreshes_with method: :morph, scroll: :preserve, this catch-up costs one round trip and preserves the scroll and the focus. This is the best practical argument in favor of pairing morphing with broadcasts: the catch-up becomes cheap enough that you actually write it.

One last thing to know in the same vein: Session#refresh also drops a refresh that arrives while a navigation is already in flight (!this.navigator.currentVisit), with no retry. It is a second, narrower path to the same silent staleness.

The decision tree

The first yes gives you the tool. Going one step further down always costs more than stopping.

The test that settles it for frames is the URL test: if there is no URL that renders this fragment on its own, a frame is not what you want. A frame is a mini browser, with an address, a loading state and a history. Without an address of its own, it brings you nothing and costs you the identifier constraint.

The test that settles it for streams is the origin test: if nobody asked for anything, it is a broadcast. If someone has just clicked and several zones have to change, it is a .turbo_stream response. These are two very different uses that share one format.

The symptom index

Symptom	Most likely cause
The form goes out, nothing moves, console: “Form responses must redirect”	`200` with HTML on a POST. Answer `422` on failure, `303` on success
The form goes out, nothing moves, no error at all	A `data-turbo="false"` ancestor, or the form is inside a frame you had not noticed
The frame empties out, “Content missing”	The response has no `<turbo-frame>` with the same id. Often a redirect to `/login`. Mark the target page with `turbo_page_requires_reload`
The stream arrives, visible in the network tab, no effect	The target does not exist in the DOM. It is a completely silent no-op
The stream does not arrive on a GET link	Add `data-turbo-stream`: without it the `Accept` header is not sent
`first child element must be a <template> element`	A `<turbo-stream>` built by hand without its `<template>`
The `Content-Type` is wrong and nothing at all happens	Turbo tests `startsWith("text/vnd.turbo-stream.html")`. Otherwise it does not intercept, and the response goes back into normal handling, with no error
The JS stops working after a navigation	Initialization on `DOMContentLoaded`, which only fires on the first load. Move to `turbo:load` or to Stimulus
The JS stops only since morphing was turned on	Inline `<script>` tags do not re-execute, and `turbo:before-cache` no longer fires
Morphing “does not work”, the page gets replaced	`<%= yield :head %>` missing from the layout: `turbo_refreshes_with` writes nothing without it
Morphing does not trigger after a form	The request has to leave from and land on the same URL
Full browser reload on every navigation	`data-turbo-track="reload"` signature mismatch. Normal after a deploy. In a loop, look for a dynamically injected asset or a service worker
Lists animate all over the place under morph	No stable `id` on the items, or an `id` duplicated elsewhere in the document, or the tag changed
Works in Chrome, breaks in Safari, under morph	`moveBefore` versus `insertBefore` in idiomorph’s pantry. It is not your code
The text the user is typing gets erased	`syncInputValue` writes the live properties, and Turbo does not enable `ignoreActiveValue`
The back button shows stale content	Intended behavior: the cached snapshot is rendered first. `turbo-cache-control: no-cache` if the content is sensitive
The back button shows a duplicated widget	The snapshot kept the DOM injected by the widget. Destroy it in `disconnect()`, not in `turbo:before-cache` if you morph
Flash messages do not appear under morph	A refresh broadcast carries no flash. And if the flash has the same `id` and the same text, the morph changes nothing at all
A broadcast updates the wrong user’s page	Stream name not partitioned. Signing is not authorizing
A broadcast arrives twice for its author	Synchronous variant with no `request_id`, or broadcast from a job
Real-time updates stop, with no error	The WebSocket dropped. Action Cable replays nothing. Catch up on the `connected` attribute
Nothing happens when the network is down, in a frame or a form	`turbo:fetch-request-error` is dispatched but nobody is listening
The browser error page appears when the network is down, on a link click	A Drive visit failing on the network triggers a full reload. `preventDefault()` on `turbo:fetch-request-error` prevents it
Changes are never broadcast from a `rails runner`	The process ends before the debounce task scheduled 0.5 s out

What changed recently

If you are rereading documentation or blog posts written before 2026, be wary of these points, all changed in version 8.0.21 of January 2026:

data-turbo-cache="false" was removed. It is data-turbo-temporary.
Turbo.clearCache() was removed. It is Turbo.cache.clear().
data-turbo-frame="_parent" was added.
The method and scroll attributes on the refresh stream action were added: they override the meta tags, broadcast by broadcast.
before and after now deduplicate siblings, as append and prepend already did for children.

And a few things present in the code but absent from the official reference, worth knowing: the turbo:before-frame-morph event, the Turbo.config.forms.mode, Turbo.config.forms.submitter, Turbo.config.drive.enabled and Turbo.config.drive.unvisitableExtensions options, and the fact that turbo:frame-render is declared cancelable even though canceling it produces no effect (the return value is discarded).

Finally, the reference versions for this article are pinned to Turbo 8.0.23 and turbo-rails 2.0.23. Almost everything above was verified by reading the code of those two versions rather than the documentation, precisely because that is where the gaps are.

Contrast cannot be checked in the mockup alone

2026-07-30T09:00:00+02:00

A brand’s design can look perfect on paper and still produce screens that some of your users simply cannot read. It happened to me recently, on an interface I develop: hundreds of texts too pale against their background, including the main button label and the tab bar, across some thirty screens. No design review had caught it.

This article covers only one part of accessibility: the contrast of text and indicators. It is visible, measurable, and still surprisingly easy to miss.

On the left, the screen the review signs off. On the right, the same screen outside, the one the user actually gets.

What the mockup does not show

A review looks at intent, on a nice screen, in good conditions. Real life also means the same screen in bright sunlight, on a cheap phone, or read by someone who is sixty. Light grey text on a coloured background can look “sleek” in the design file and become invisible outside.

In this interface, much of the text sits on a gradient, a translucent layer or a blend of tints. The colour to judge is the one obtained once those layers are composed, in every theme and every state, not only the value written in the file. The mockup can and should eliminate some mistakes. On its own, it cannot prove that the final implementation remains readable everywhere.

The colour written in the file is a flat fill. What gets painted is a gradient, and the white text drops to 1.5:1 on it, where AA asks for 4.5.

What a green score does not prove

The next reflex is to run Lighthouse, get a nice green score and tick the box. But a green score does not prove that every piece of text is readable. It means the automated checks found no problem. Gradients, background images and some overlapping layers remain difficult to analyse: they need a dedicated check.

The most instructive trap came from our own check. To judge a gradient, it computed the average colour. A plate going from dark to light therefore produced a reassuring average, a colour painted nowhere on screen. The test went green on a fiction.

The same gradient judged two ways. On the average, the check goes green. On the worst spot, it fails.

A check that shows green on a colour that does not exist sells peace of mind while guaranteeing nothing. We fixed it to judge the worst spot of the gradient, not its average.

Why it was a product problem

The worst cases were not decorative details. They were the button everyone taps, the navigation bar, and the little frame that shows where you are when navigating by keyboard. The elements everyone touches, barely visible to a chunk of people.

Text that is too pale is not “a bit less pretty”. It is a user who cannot find the button, who gives up, who calls support. On a consumer product, readability is a conversion number before it is a compliance checkbox.

What we fixed, and what remains

We combined the three levels that were missing: design review, automated checks and inspection of the interface actually rendered in a browser. None is enough on its own. Together, they uncover obvious mistakes, implementation mistakes and the cases automation cannot decide.

The point that matters to a decision-maker: no brand colour moved. What changed is the ink on top. Each type of background now has its own text colour, chosen once in the design system instead of eyeballed screen by screen. We went from hundreds of insufficient cases to a handful.

That handful consists of white text on the brand gradient, where no single text colour meets the threshold across the whole surface. Knowing about them does not make them compliant: they are residual issues still to be fixed by changing the composition, for example with a local background or different placement, without necessarily touching the palette.

A guardrail, not an audit

The guardrail is a small test that runs in seconds on every change. It does not replace an accessibility audit: it does not even cover all of accessibility. It does one narrower, useful job. It stops a new colour, a rebuilt component or an added screen from slipping back below the bar without anyone noticing.

The useful question is not “what is our score?”

Accessibility is not a favour done for a minority. It makes the product usable by people who age, who read in the sun or who simply have average eyesight: in other words, everyone sooner or later.

Since June 2025, the European Accessibility Act has also applied accessibility requirements to defined categories of products and services, including e-commerce, banking, transport and electronic communications. But compliance is not the best reason to care, and this contrast test is obviously not enough to establish it.

For a decision-maker, the useful questions are simpler: how many of our users can actually read our screens? What stops us from becoming unreadable again next month? If the answer is “the team’s vigilance”, there is no answer.

In this case, the first diagnostic and the guardrail took half a day. If you have a consumer product and nobody has ever checked the contrast of the interface actually shipped, we can look at it together.

When AI becomes your single point of failure

2026-07-27T09:00:00+02:00

A few days ago, my monitoring dashboard sat frozen for three days. It aggregates the application errors from my projects every hour. For three days, the tile displayed perfectly plausible numbers. They were three days old.

The monitoring service itself had never stopped answering. The data was there, available, one API call away. What had failed was the piece I had slipped into the middle of the pipe: an AI session.

A silent failure, the worst kind

The unpleasant part of the story is not the outage. It is that the outage did not look like one.

An agent that crashes shows an error, raises an alert, gets noticed. Here, the hourly agent failed cleanly, wrote nothing, and the page kept serving the last known state with its usual formatting. Nothing blinked. I found out while looking for something else.

The cause was mundane: the authentication on the command line tool carrying the session had expired. No quota exceeded, no model unavailable, no bad answer. Just a stale token on a component I had never counted as part of my data collection chain.

Why the AI was there in the first place

Convenience, and that is the interesting part.

Access to the monitoring service already existed as a tool wired into my assistant. Writing a prompt along the lines of “fetch the unresolved errors, classify them, write the summary” takes ten minutes and works on the first try. Writing the equivalent API client, handling pagination, fields and edge cases, takes half a day and produces no impressive demo.

So the decision was rational the moment I made it. It was much less so a month later, when that shortcut had become a production link carrying the only view I had of my applications’ health.

It is a pattern I see a lot right now in companies “adding AI” to their processes. The prototype is spectacular, shipping it is painless, and nobody circles back to ask what happens the day the newest and least deterministic component in the chain stops answering.

The fix, two hundred boring lines

The replacement is about two hundred lines of Python. It reads the monitoring service’s REST API with a dedicated token, filters out the projects that are none of my business, applies a keyword based classification and writes the result. No AI anywhere on the path.

The model did not disappear, it moved. Fine grained triage, phrasing a diagnosis, deciding whether to create a task: that stays as a layer on top, one that can fail without consequences. If it does not run, I lose commentary. Before, I lost the data.

The difference fits in one sentence: the truth shown on my dashboard no longer depends on an assistant’s authentication state.

This was not the first warning

A few weeks earlier, the agent that watches the other agents started sending me outage alerts for services that were perfectly healthy. The reason: it computed the current timestamp itself, and the model got the day wrong in certain time windows. Eight false alerts before I figured it out.

The fix was to forbid it from producing a date at all. A date is something you ask the operating system for, not something you infer.

Here again, the lesson is not “AI is unreliable”. It is more precise than that: a language model is non deterministic by construction, and that is exactly what you want from it when you need rephrasing, summarising or judgement calls. The problem only shows up when you also hand it tasks where non determinism is a defect: counting, dating, adding up, fetching a value that already exists somewhere.

The rule I apply now

My personal system currently runs forty eight active agents. Twenty nine of them contain no AI at all. They are scripts: they read an API, compute, write a file, send a notification. They run on time, they cost nothing, and their failure mode is legible.

The other nineteen use a model because they do something a script cannot: read a client conversation and extract an intent, draft a text, rank heterogeneous signals, propose three options and recommend one.

That is where I draw the line. AI above the system, for judgement. Never inside it, on the path where data is acquired or computed.

The question to ask before putting it everywhere

For an executive evaluating an automation with AI inside, the useful question is not “does the demo work”. It is this one, in two parts.

If the model is unavailable for three days, what exactly stops? And does anyone notice, or does the screen keep showing numbers that look normal?

If the second part is fuzzy, the problem is not the AI. It is that a dependency was added without being held to the standards every other dependency is held to: failure detection, an explicit degraded mode, and a clear assumption about what happens when it is not there.

An automation that cannot tell you it is down is not an automation, it is a display.

If you have a process where AI settled in without that line ever being drawn, we can look together at what deserves to stay and what would be better off as a script again.

My Postgres high availability wasn't, autopsy of an outage

2026-07-22T18:00:00+02:00

Yesterday evening, every one of my internal services and the software I host for my clients became unreachable for several hours. A saturated Postgres database, a high-availability setup that did not play its part, and a Scaleway incident on top. Here is the autopsy, no filter, because an outage you tell honestly is worth more than one you paper over.

The trigger, or rather the triggers

At 10:15 PM (Paris time), Scaleway lost a node in its block storage cluster in fr-par-1 (incident bsp2y5fysy9w). On the infrastructure side the effect was immediate: virtual machines stuck, and above all managed databases frozen on storage that had become unreachable.

At the very same moment, on my end, I had kicked off a batch of contact-enrichment jobs on Argos, my CRM. That kind of batch opens a lot of Postgres connections, and fast. Was it the batch that saturated the pool, or was the database already suffering from the Scaleway storage? I do not have a clean answer, and that is exactly the trap of correlated incidents: two plausible causes landing in the same window, and a doubt that only lifts after the fact. What I do know is that the two fed off each other. A database that responds poorly, connections piling up instead of being released, a batch that keeps asking for more. The pool hits its connection limit, and from there no application can open a single one. Everything falls in cascade.

The real problem: an HA setup that wasn’t one

My database ran in high availability, two nodes. Reassuring on paper. Except that both nodes lived in the same datacenter, fr-par-1. When the block storage layer of fr-par-1 went down, my two replicas left together, in the same second. That is the lesson I hold onto the most: redundancy only protects against what it isolates. Mine covered the failure of a process or a machine, not that of an entire zone. I had taken out insurance against one risk, not against all of them.

Worse, restarting the database was impossible. The managed Postgres engine stayed hooked to the failing storage. I could kill the zombie connections and restart my applications all I wanted, the final recovery no longer depended on me: it was suspended on Scaleway’s repair. Finding yourself a spectator of your own outage, with no lever at all, is the most unpleasant moment of the evening.

Getting out of it

Things unblocked during the night, by combining three things. I cut the connections left open on the Postgres side, I restarted the applications to start again from clean pools, and Scaleway eventually repaired the storage node. That last point was the decisive factor: without it, the rest was useless. My first two actions only set the stage so everything could come back cleanly once the infrastructure returned.

What I take away, and what I have already done

A good incident is the one that finally makes you do what you were putting off. I tackled three things right away.

PgBouncer in front of Postgres, first. A connection pooler I had wanted to set up for a long time without ever getting to it. It caps the number of connections and stops a batch from starving every other application. It is in place.

A read-only failover in another zone, next. My two HA nodes in the same datacenter were the heart of the problem. I added a read-only replica elsewhere, so that a Scaleway zone going down no longer takes everything with it in one block.

Observability on connections, finally. Watching pg_stat_activity and how full the pool is, to see saturation climb and fire an alert before it kills everything, instead of discovering it once the service is already down.

The lesson, in one sentence

An infrastructure dependency, however solid on paper, stays a single point of failure until you have explicitly isolated it. And redundancy you have never tested against the right failure mode is redundancy in name only.

If you have infrastructure you keep calling “highly available” without having checked against which kind of failure exactly, we can take a look together, rather than finding out on some Tuesday evening.

How much am I owed, in total, right now?

2026-07-13T18:00:00+02:00

All financial figures and client names in this article are fictional. The screenshots show real screens, filled with made-up data.

When you run a company on your own, one question comes up more often than any other. Not “how much did I invoice last month”, not “what’s my yearly revenue”. The real question, the one that decides everything, is: how much am I owed, in total, that I’m going to collect?

Not within a 30 or 90 day window. In total. Everything invoiced and not yet paid, with no time limit, and whatever is overdue clearly flagged.

And the problem was that nothing answered it. My accounting software told me what was invoiced. My CRM what was in the pipe. My bank account what had already landed. Three partial truths, in three different tools, that I had to cross-reference by hand in a spreadsheet on a Sunday evening. Which is to say: never.

So I stitched the pieces back together at the source, inside Argos.

Argos, from CRM to treasury cockpit

Argos is the CRM I built for SXN Labs. It started out managing contacts, deals and quotes. The latest project was to graft a treasury-tracking layer onto it, with one rule I set for myself: show facts, not predictions. I didn’t want a model guessing my future. I wanted the truth at time T, the kind I can verify line by line.

The result is a dashboard whose default state is a sentence I love to read: “Nothing needs your attention.” When something is off, it surfaces it. When everything is fine, it says so, and then it shuts up. At the top of the screen, a handful of numbers, all factual, all up to date, without me entering anything.

The Argos Cash dashboard at a glance (fictional data).

Under that calm surface, there are three small technical challenges I find interesting.

All the pending cash, at once

The central number is “to collect”: the sum of every invoice issued and not yet paid. No sliding window, no arbitrary horizon, just the total.

But a raw amount isn’t enough. What I want to see at a glance is the ex-VAT figure (what’s actually mine), the VAT share (which I’m only holding for the tax office), and above all what’s overdue. A client who has owed 8,400 € for ten days is not the same piece of information as a client who has until the end of the month to pay me. The first calls for a reminder, the second doesn’t.

Argos computes that ex-VAT / incl-VAT / overdue split from Pennylane invoices. And this is where using Pennylane as both bank and accounting software pays off. No bank reconciliation to do: payments are natively matched to invoices, transactions arrive already categorized. I consume the data as-is, I don’t reclassify anything by hand.

Two accounts, one treasury

My treasury lives in two places. Pennylane for day-to-day banking. Spiko for idle cash, parked in tokenized money-market funds that earn a little every day.

Total treasury is therefore the sum of the two pools. Because they are physically distinct, a bank account on one side and fund shares on the other, there’s no risk of counting the same euro twice. And if one of the two sources goes down, the system falls back cleanly on the other rather than showing a phantom balance.

A small anecdote for anyone who has integrated an API before: Spiko returns a lovely 403 from Cloudflare if you don’t send a browser User-Agent. The classic “your urllib is blacklisted by default”. Five minutes of confusion, one header, and you move on.

And everything else, in one place

Once cash-to-collect and treasury were in place, I added the other facts that weigh on a small company: monthly recurring revenue, what was actually collected this month, and an estimate of the dividend I could pay myself, net of tax. Always the same logic: observed numbers, not promises.

And because Argos isn’t only a financial tool, the same screen also aggregates the operational side: are my deployed applications healthy, how many servers are tracked, which deploys happened today, is my inbox up to date, are my mileage entries logged. Finance, ops and admin, in a single glance. All crowned by that famous “nothing needs your attention” when the checklist is green.

The twist: less interface, not more

Here’s the counter-intuitive part.

The natural tendency, when you add data to a tool, is to pile on screens, charts and filters. I did the opposite. I shrank Argos’s interface surface to the minimum, and I now drive it almost entirely through MCP.

For the uninitiated, MCP (Model Context Protocol) lets you expose an application’s functions as tools an assistant can use. Concretely, Argos exposes tools like list_deals, create_quote, get_metrics_summary, daily_briefing. As a result, I barely click anymore. I talk to my CRM. “Summarize the treasury”, “which quotes are signed but not yet invoiced”, “create a deal for this prospect”. The answer comes back, or the action happens, without me opening a single page.

What I understood while building this: for a tool I use alone, the most efficient interface isn’t a pretty web page. It’s a good, well-described API that an AI can operate on my behalf. The graphical UI becomes the exception, reserved for the moments when I actually want to see something.

A word on trust, because the question always comes up: this whole financial pipeline is read-only. No invoice creation, no transfer, no automated movement of money. The system reads, aggregates, displays. It never touches the money. It’s a sensor, not a hand.

Cash in sight, without going to look

One last detail remained, and it might be the most pleasant one day to day.

A dashboard, however accurate, is useless if it’s buried in a tab I open once a week. So I took it off the screen. I put a small e-ink display, a TRMNL, on the shelf in my office. It cycles the Argos Cash screen (to sign, to invoice, to collect, treasury, overdue invoices, collected this month) alongside other CRM views and more general ones: the weather, a photo, and the rest.

The TRMNL on my desk: treasury, ambient (fictional data).

The effect is surprisingly strong. Financial information is no longer something I go and fetch: it drifts through my field of view several times a day, between the weather and a photo, next to the hat and the sunglasses. I look up, and often enough, I know where I stand. No notification, no app to open. Just a calm number, updated on its own, in black and white on electronic paper.

What I take away

Building this thing for myself confirmed a conviction: the best tools you can make are often the ones you use first yourself, with real needs and real irritations. Argos’s treasury tracking was born from my own question, the one about the cash I’m owed. And that demand, the kind that lets nothing slide, ends up seeping into the product I offer my clients.

Three ideas, if I had to sum up: stitch the data back together at the source instead of in a spreadsheet, show verifiable facts rather than predictions, and accept that the best interface is sometimes the one that doesn’t exist.

Next time you wonder how much you’re really owed, ask yourself another question: does your tool answer you at a glance, or do you still have to open a spreadsheet on a Sunday evening?

Ripping Algolia out of a healthcare app, the dependency that no longer earned its place

2026-07-06T18:00:00+02:00

On ORIGAMI, the healthcare business application I build for SOS Médecins (see the case study), patient search ran on Algolia. A hosted search service, fast, forgiving of typos. Last week I unplugged it entirely. The whole change comes down to two numbers: 33 lines added, 331 removed. And on the user’s side, nobody noticed a thing. That was exactly the outcome I was after.

Why Algolia was there

The reflex is a familiar one. You need a “real” search, instant, typo-tolerant, surfacing the right patient even when you fat-finger three letters. You glance at Postgres, decide it’ll be a hassle, and wire in a specialised service. Algolia does that job very well. Within a few hours the search feels smooth and the matter seems settled.

Except “wiring in Algolia” is never a single line. In the code it meant: a Ruby gem, an npm package on the front end, an initializer to configure, API keys exposed to the browser, a job that reindexed patients into Algolia in parallel with the database on every change, and three Stimulus controllers talking directly to the Algolia client. A dependency isn’t a button you flip: it’s a surface you adopt, upgrade, monitor, and pay for every month.

The real requirement, once you lay it flat

The question I hadn’t asked myself in a long time: what search do I actually need here?

The answer is modest. We look up patients within the scope of a care structure. The dataset runs to hundreds of thousands of records, not tens of millions. The fields are simple: a last name, a first name, a few identifiers. The real need is to find “Smith” when you type “smth”, and to find it fast.

For that, Postgres is more than enough, even at that scale. The pg_trgm extension computes trigram similarity: it absorbs typos and partial prefixes without you writing a single distance algorithm by hand. A dedicated table materialises each patient’s search document, a job keeps it fresh on change, and the query runs in the same database, in the same transaction, with no network round-trip to a third party. That internal backend already existed and had been the default for a few weeks. Algolia was just a second engine we kept around out of caution.

The real argument: health data on the move

KISS is a good reason. It isn’t the best one here.

Sending patient names to a search index hosted abroad means letting health data leave its own infrastructure. It pulls in health-data hosting rules, GDPR, the principle of data minimisation. Even when everything is contractually airtight, it’s one more governance surface: another place sensitive data flows through, another processor to audit, another clause to defend the day someone asks the question.

So removing Algolia isn’t just dropping a dependency and a €250-a-month bill. It’s removing a reason to worry. Patient data no longer leaves the database. There’s no external index to secure, no API keys to leak from the front end, no processing agreement to keep an eye on, for a feature we already knew how to do in-house.

What the switch was really about: nobody feeling a thing

Swapping one search engine for another on software used in production isn’t a matter of flipping a global switch. The bar was clear: on the user’s side, search response times had to stay rigorously identical. Not “roughly as fast”, identical. A patient search that lags by a tenth of a second, on a dispatch desk, gets noticed immediately.

To validate that without risk, I’d added a per-user boolean, internal_patient_search, that turned the new engine on for a handful of accounts only. A selective activation mechanism, not a forgotten flag: long enough to run both backends side by side, compare response times in real conditions, and confirm that the move to Postgres was felt nowhere.

Once that validation was done, the flag had done its job. I removed it at the same time as Algolia, in the same pass: the database column, the checkbox in settings, the permitted params in the controller, the labels in two languages, and three now-pointless tests. A single boolean already touches six corners of the code; the discipline isn’t never adding one, it’s dismantling it the moment it has stopped being useful.

What this is not

This isn’t a case against Algolia. It’s an excellent product, and there are contexts where I’d wire it back in without hesitation: a large e-commerce catalogue, a public-facing search, typo tolerance across millions of documents. The tool isn’t the point.

The point is the question you ask before adopting it. Not “what’s the best search?”, but “what search do I need, for this dataset, in this context?”. When you take the time to answer that honestly, you often avoid importing a dependency, a recurring bill, and, in healthcare, a piece of sensitive data that had no reason to travel.

Simplicity is a decision

Absorbing complexity on the provider’s side so the software stays simple for the client applies just as much to the complexity you inflict on yourself. The best code isn’t the one you write most elegantly: it’s the one you remove because you no longer need it, and will never have to maintain again. 331 fewer lines, one fewer dependency, health data that stays home, and a strictly identical interface for the user, response times included. That’s what a good day looks like.

If you’ve got an external dependency under the hood costing you every month without you really knowing what it buys you, we can look together at what deserves to stay and what can come back home.

AI didn't replace my job, it moved my ceiling

2026-06-22T11:00:00+02:00

People regularly ask me whether AI is going to replace developers. The question is backwards. On my projects, AI hasn’t removed a single skill. It moved a constraint I had taken for granted for ten years: my own time.

The real ceiling was never the code

When you build a serious line-of-business application alone or in a pair, what caps your output isn’t typing speed. It’s the number of hours a human can sustain in a week without breaking quality. A small editor spends their life arbitrating: this week I wire up that integration, so I don’t touch the billing module; this quarter I push a certification through, so the mobile rework waits.

Simon Willison puts it well in a recent post: if AI hasn’t triggered a wave of developer layoffs, it’s because coding is only a small part of the job. Out of 160 companies that filed layoff notices in New York in 2025, “not a single one checked the AI box.” Deciding what to build, specifying it, verifying it, being accountable for what you ship, understanding the business context, none of that automates.

I agree. But I draw a slightly different conclusion than he does. If code is only a small part of the job, then accelerating the code doesn’t change the nature of the work, it changes its capacity. And for a small outfit, capacity is almost everything.

What it concretely changes

Three things shifted in the way I work.

Scoping. I used to instinctively drop the “correct but expensive” features: the clean degraded mode, the monitoring, the integration tests on an external feed. Not out of laziness, out of a time budget. Today the marginal cost of doing it right has dropped. I wire in the safety net because writing it no longer costs me half a day.

Pricing. A fixed-price quote is a bet on time. When the output ceiling rises, the same scope ships faster, or a more ambitious scope fits the same envelope. That doesn’t mean billing less; it means delivering more value for the price, and moving on to the next job sooner.

Running the project. More back-and-forth with the client, and earlier. Mocking up a variant in an afternoon instead of a week means being able to say “look, here’s what it looks like” before freezing a decision. Velocity isn’t there to produce more lines; it’s there to shorten the loop between a business idea and something you can actually touch.

What it doesn’t change (and the anxiety that comes with it)

There’s another, darker reading going around among developers. A post that circulated recently tells the same story from the inside: ten years building deep expertise (finance, debugging, architecture) only to watch it become “promptable” in a few weeks. The anxiety isn’t unemployment, it’s the commoditization of mastery.

I understand the vertigo. But I think it conflates two things: knowing how, and knowing what to do and being accountable for it. AI makes the first abundant. The second (deciding, specifying, verifying, carrying responsibility for what ships to production on a sensitive system) stays rare, and stays mine.

The job doesn’t disappear. It moves up a notch: less production, more judgment.

Stepping back

Let me zoom out, owning that this is an opinion and not a proof.

There’s a lot of talk about France’s demographic problem: an inverting age pyramid, the large cohorts retiring, a thinner generation behind them. Public debate fixates on a single variable, the retirement age. It’s one variable among several. Producing more per head is another, and tooling that raises one worker’s capacity feeds directly into it.

I’m not claiming AI fixes demographics, that would be exactly the kind of marketing shortcut I spend my time criticizing. But when one worker can carry a volume of output that took two yesterday, it counts in the equation. It’s less divisive than moving an age slider, and probably more durable. Provided the gains go to the value produced, not to stacking tools for the sake of tooling.

Conclusion

AI didn’t replace my job. It removed the dumbest limit weighing on it: the fact that a day has twenty-four hours. What stays rare (deciding, specifying, verifying, being accountable) hasn’t moved an inch. That’s precisely where the value of an editor lives, solo or not.

If you run a company and you’re wondering where AI has a real effect rather than a cosmetic one, that’s exactly the kind of context we can look at together, and settle what genuinely deserves to be automated.

E-invoicing 2026: the part the platform won't do for you

2026-06-08T15:30:00+02:00

September 2026 is everywhere. In public campaigns, in tax authority emails, in conversations with accountants. The date has entered the scenery, which is not a bad thing: at least this time, nobody should discover the reform the night before with a surprised face and three spreadsheets open.

The problem is not that nobody talks about September 2026. The problem is what people put behind that date. Many still hear it as “the start of e-invoicing”, or as the deadline for large companies that must start issuing. For a small business, the concrete effect is more immediate: from 1 September 2026, your suppliers may send you real electronic invoices, and you must be able to receive them.

Receiving comes before issuing, and it’s exactly the part you don’t control. But the real question, behind the date, isn’t which tool to buy: it’s who is going to wire all this into your software. And there, neither the platform nor the accountant holds the role.

What changed in the system

For two years, the announced design relied on the PPF (the public invoicing portal) as a platform invoices could transit through. The system has since been narrowed: the PPF is no longer the public transit platform companies were expecting, but the infrastructure for the central directory and for reporting data back to the tax authority. Its job is to know who receives what, through which platform, and to concentrate the tax data needed by the DGFiP.

Concretely, that means three things:

B2B invoice transit now goes through certified platforms (the former PDPs), registered by the tax authority. No simple public option where everyone deposits and retrieves invoices.
Chorus Pro remains the reference platform for B2G, invoicing the public sector doesn’t change channel.
Penalties have been strengthened: the per-invoice fine goes from €15 to €50 per invoice, e-reporting from €250 to €500 per transmission (with annual caps).

In the official list at the time of publication, examples include familiar names such as Pennylane, Qonto, Sage, Cegid, Tiime, Indy, Yooz or Esker. This is not a recommendation list. It’s mostly a useful reminder that reception won’t go through a magic public form, but through an intermediary you actually choose.

The operational calendar remains easy to remember: mandatory reception for everyone on 1 September 2026, issuance for large companies and mid-caps on the same date, issuance for SMEs and micro-businesses a year later.

Why reception is the trap

When people talk about September 2026, the natural reflex is to ask: “do I have to issue?” If you’re an SME or a micro-business, the answer is often no, not yet. That’s where the misunderstanding starts.

When you issue, you hold the schedule. You pick your platform, you migrate when you’re ready, you test on your own flows.

Receiving is the opposite: your supplier decides for you. From 1 September 2026, the moment one of your large or mid-cap suppliers switches to electronic issuance (and they’re required to by that date), you must be able to ingest their invoice. You choose neither the timing, nor the format, nor the platform on the other side. You’re on the receiving end, literally.

And “being able to receive” isn’t having an inbox. An electronic invoice, in the sense of the reform, is not a PDF attachment. It’s one of these baseline formats:

a pure structured XML (UBL or CII),
or a Factur-X: a human-readable PDF/A-3 with the same CII XML embedded inside for the machine.

You can’t tell them apart by eye: both open in a PDF reader. To find out which category your software currently produces, drop one of your invoices into the Factur-X pre-check — the analysis runs in your browser, the file goes nowhere.

Receiving properly therefore means connecting to a certified platform, pulling the flow, parsing the XML, validating it, then reconciling it against your purchase orders and your bookkeeping. It’s an integration project, not a setting to toggle. And it’s exactly the kind of work you underestimate until you’ve done it.

The format isn’t the problem

I wrote two open-source gems around this: einvoicing for the core (generating and reading Factur-X, validation, CII profiles) and einvoicing-connect for the plumbing (Chorus Pro, certified platforms, e-reporting). After running them on real flows, one thing became obvious: the format is the easy part.

Producing a compliant Factur-X is mechanical. A PDF/A-3, a CII XML attached with the right filename and the right profile, a handful of validation rules. A library does this very well:

invoice = Einvoicing::Invoice.new(profile: :en16931)
invoice.add_line(description: "Service", quantity: 1, unit_price: 950_00)
facturx = invoice.to_facturx(pdf: rendered_pdf)   # PDF/A-3 + embedded CII XML

The real work is elsewhere: in the business reconciliation. An incoming invoice has to be linked to the right supplier, the right purchase order, the right VAT, and you have to handle credit notes, partial invoices, cent-level discrepancies, identifiers that never match on the first try. The XML hands you clean data; it doesn’t tell you what to do with it inside your accounting. That’s where 90% of the effort goes, and it’s the part no platform will do for you.

The role nobody holds

Look at who actually shows up on this. The certified platform delivers a clean flow to your door. The accountant reads the result once it’s in the books. Between the two, there’s a space neither of them covers: making your software (your business app, your ERP, the spreadsheet everything revolves around) ingest that invoice, reconcile it, and do something useful with it. That space is integration. That’s a developer’s job.

Concretely, it comes down to three pieces:

The plumbing. Connecting your existing software to the certified platform’s API so the incoming flow lands inside your system, not in yet another portal someone has to check by hand. Nobody else knows your data model.
The reconciliation. The famous 90%: linking each received invoice to the right supplier, the right purchase order, the right VAT, handling credit notes and discrepancies, inside your business model. No platform will do it, because no platform knows your business.
The lifecycle. The reform requires you to report invoice statuses (received, refused, paid…). Those transitions have to live in your real workflow, not in a separate interface nobody will ever update.

That’s where I sit, and it’s what I wanted to make clear here: I don’t sell a platform. I make your existing software speak the language of the reform (ingest, reconcile, report), where the platform stops and your business begins.

The right question to ask now

The reform is not “2026 for large companies, 2027 for small ones”. It’s 2026 for everyone on reception, then 2027 for part of the market on issuance.

So the useful question is not only “when do I have to issue?” It’s: “on 1 September 2026, can I receive a structured electronic invoice and integrate it without re-keying it by hand?” If the answer is no, this isn’t next year’s problem. It’s this summer’s.

Picking a certified platform, wiring up reception, testing the parsing on a few real supplier invoices: that’s a calm few-weeks job if you start now, and a painful one if you wait for the first supplier to switch without warning.

Preparing reception before it hurts

A business application, an ERP held together around spreadsheets, an accounting workflow that still works because someone re-keys everything by hand: e-invoicing will quickly reveal the places where the system mostly runs on human patience.

This is the kind of work I handle at SXN Labs: clarify the real need, choose the right level of automation, wire up reception, and make sure invoices land in the right place without adding yet another overbuilt system. If your e-invoicing reception is about to become a painful project, drop me a line.

Connecting INSi with strict TLS and clinical continuity

2026-06-04T18:00:00+02:00

One Tuesday morning, every call from a production healthcare app that I build and maintain to the French national INSi teleservice started failing server-side. Patient identity verification was completely broken.

On the user side, the software did what it was supposed to do: it did not show a stacktrace, it indicated that INS verification had not completed. The patient was there, the care flow could continue, but the identity remained unverified.

The underlying error, captured in Sentry, was a single line:

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0
  certificate verify failed (self-signed certificate in certificate chain)

Diagnosis took twenty minutes. The clean fix, two hours. But the point was not to rework the UX or the business behavior. The INSi integration was already running in production with strict TLS verification and correct behavior on failure; the incident mostly exposed one operational subject that had to be made explicit: the IGC-Santé trust chain.

The service had to work again, without weakening TLS, while preserving an important property: an external failure should not block clinical work.

There is a wrong answer to this problem, copy-pasted everywhere on forums, that you absolutely must avoid when you ship patient identity data over the wire. It fixes TLS about as well as removing the engine light fixes a car.

The Actual Need

The business need was not “complete a TLS handshake”. It was simpler:

Verify a patient’s INS identity when the teleservice responds.
Let the clinician keep working when the teleservice does not respond.
Clearly mark the identity data as provisional until it has been verified.
Know before the next outage that a certificate is about to expire.

TLS was only one part of the problem. Important, but not enough. A critical integration also needs an explicit answer for the days when the external dependency does not respond.

What INSi Does

INSi is the CNAM (French health insurance) teleservice that lets a clinical app fetch or verify a patient’s National Health Identifier from civil traits: name, first name, date and place of birth. It is a central building block for producing, exchanging, and archiving healthcare data against the right patient identity.

The endpoint lives on services-ps-tlsm.ameli.fr. It’s SOAP, authenticated by a client certificate issued through the ANS Portail de Confiance. On the server side, the TLS chain roots in the IGC-Santé root CA, the French state authority for healthcare PKI.

That root is in no default system trust store. Not Debian, not Ubuntu, not macOS, not the Mozilla bundle embedded in most HTTP libraries. It’s a specialized government PKI, separate from the public web PKI. In other words, if you do not add it explicitly, OpenSSL will not discover it through administrative telepathy.

The Bad Fix

If you search “OpenSSL self-signed certificate in certificate chain Ruby”, you’ll find ten StackOverflow answers all saying the same thing:

# DO NOT do this on a patient identity flow
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

On a personal script scraping a site with a self-signed certificate, that is between you and your conscience. On a flow that ships a patient’s social security number, name, and date of birth to a service authenticated by client certificate? Absolutely not.

Disabling verify_mode means:

Accepting any certificate on the other side, including a MitM attacker on the network.
Punching a hole in the only cryptographic guarantee that the machine you’re talking to is in fact CNAM’s.
Carving into the codebase, durably, a security regression no one will ever revisit.

And for nothing: the real answer is quick, documentable, and keeps security in place. A useful detail when the payload is patient identity.

The Clean Fix

ANS publishes the IGC-Santé chain publicly on its site (root + intermediates, PEM format). The right reflex:

Download the official chain from the ANS portal.
Verify fingerprints: SHA-256 of the downloaded cert compared against the one served by the live endpoint, and against the one published by ANS. Three sources, one hash. If any of the three disagrees, stop.
Bundle it into the project, under version control, distinct from client certificates (which stay in encrypted credentials).
Point OpenSSL at it when building the SOAP client.

In a Rails app, simplified, this is what Ameli::Insi ends up looking like:

class Ameli::Insi
  def http_client
    Savon.client(
      wsdl: wsdl_path,
      ssl_cert_file: client_cert_path,
      ssl_cert_key_file: client_key_path,
      ssl_ca_cert_file: igc_sante_bundle_path, # bundled public chain
      ssl_verify_mode: :peer                   # strict verification stays on
    )
  end

  private

  def igc_sante_bundle_path
    Rails.root.join("lib", "certs", "igc_sante.pem").to_s
  end
end

To validate end-to-end before even redeploying, openssl does the job:

openssl s_client \
  -connect services-ps-tlsm.ameli.fr:443 \
  -CAfile lib/certs/igc_sante.pem \
  -servername services-ps-tlsm.ameli.fr \
  -showcerts < /dev/null 2>&1 | grep "Verify return code"

Expected output: Verify return code: 0 (ok). From there, the Ruby client works again, in VERIFY_PEER, with no security downgrade.

The Useful Behavior

Once the root cause was fixed, one interesting point was worth making explicit: why had the incident not blocked the clinician?

Because the software did not treat an INSi failure as an exception to throw on screen, but as a business state. When INSi answered, patient identity was verified. When the teleservice did not answer, the technical error stayed in Sentry and the interface told the clinician that INS verification could not be completed.

The application boundary looks like this, simplified:

def fetch_by_traits(patient)
  response = http_client.call(:fetch_by_traits, message: payload_for(patient))
  Ameli::Insi::Identity.from_soap(response)
rescue HTTPI::Error, Savon::Error => e
  Sentry.capture_exception(e, extra: { patient_id: patient.id })
  raise Ameli::Insi::TeleserviceUnavailable
end

The calling controller rescues TeleserviceUnavailable and keeps a provisional identity (the civil traits typed by the clinician, tagged “INS not verified”), with a banner explaining INSi is down and that the record must be re-verified later. The clinician keeps working, the patient isn’t blocked, and the data will be reconciled at the next successful call.

That was already the useful behavior. Not spectacular, not great demo material, but it is what matters in production: an external dependency going down should not stop the care chain. It should become an explicit degraded mode.

The Invisible Work

This incident also brought back an operational point that is easy to underestimate. INSi, MSSanté, and Pro Santé Connect client certificates are renewed manually on the ANS Portail de Confiance, then stored in encrypted credentials. The app can work perfectly for months, until one deadline arrives silently.

The day one expires, you get the same outage again, with a familiar smell and a perfectly reasonable urge to insult a calendar.

So, right after the fix, I added a daily job that walks the inventory of bundled certificates: public chains and client certificates. It reports to Sentry any certificate within 30 days of expiry, then escalates at 7 days or once a certificate has already expired.

I also added a renewal runbook versioned in the repo (lib/certs/README.md), with the PFC procedure step by step. No one will see it as long as it works. When it threatens to break, it will be an actionable warning, not a surprise outage.

A quick map of French healthcare PKI

For anyone discovering the ecosystem, the building blocks look alike and it’s easy to get lost:

INS: the patient’s national health identifier (NIR or NIA + traits). The data.
INSi: the CNAM teleservice that lets you fetch / verify an INS. The API.
MSSanté: secure messaging between professionals and with the patient. Separate PKI, certificates issued by MSSanté operators.
Pro Santé Connect: the state SSO for healthcare professionals (dematerialized CPS card, OIDC).
IGC-Santé: the shared PKI root that signs most of the ANS server side.

Each block is documented, each chain is public and verifiable. The trap is treating this as an annoying technical detail when it is part of the product: identity, security, continuity of care, and operations.

What I Keep From This

When a TLS integration breaks in production, the right answer is almost never “disable verification”. It’s: find the missing trust anchor, make it explicit, version it, audit it over time. The VERIFY_NONE reflex saves ten minutes now and leaves a security debt to age quietly in the codebase.

The other point, more product than TLS, is that any critical integration needs a degraded mode. An external teleservice going down is normal over a decade of operations. Here, that decision already existed on the user side: INS verification failed, the clinician was informed, and care could continue.

The real work was the whole loop: understand the clinical need, make the trust chain explicit, preserve security, rely on the existing business fallback, then monitor certificates so we do not replay the same scene three months later in a different outfit.

If you have one of these at work

French healthcare integrations (INSi, MSSanté, Pro Santé Connect, DMP) are a mix of PKI, certificates, WSDL files, and ANS procedures that require more patience than genius. They work. But you need to frame the business need as much as the technical connection.

This is the kind of work I handle at SXN Labs: understand what actually needs to keep working, simplify the scope, connect it properly, and leave behind a system people can operate. If you have a healthcare teleservice stuck somewhere, drop me a line.

Controlling my Intex spa without its app

2026-05-31T18:00:00+02:00

I have an Intex PureSpa Baltik inflatable spa in the garden. It works great. The iOS app that comes with it, on the other hand, is a disaster: you need a Tuya cloud account, auth drops every three days, half the commands take 10 seconds to land, and the UI looks like a POC abandoned in 2018. For a device that lives on my Wi-Fi 3 meters from my Mac, the round trip through a server in China felt pointlessly absurd.

So I dumped the app and wrote my own. One weekend of reverse engineering, then a few evenings stacking the features the official app will never ship. Here’s how it turned out.

Reverse engineering in 30 minutes

I got insanely lucky: mathieu-mp/aio-intex-spa had already done the thankless work. The spa’s Wi-Fi module listens on TCP port 8990, the protocol is binary with a simple checksum (modulo 0xFF, not 0x100, that’s the classic trap), and the functional commands (power, heat, filtration, bubbles) are toggles: you read the current state and only send if the desired state differs. Idempotent by construction.

I validated it byte-for-byte against my actual spa with a standalone probe.py (stdlib only, zero deps), then packaged that into a pure protocol.py layer that tests offline.

Three invariants drive the whole architecture:

One TCP connection only. The firmware accepts a single client at a time on 8990. Everything goes through one IntexSpaClient with an asyncio lock, owned by one Supervisor.
Polling doubles as keepalive. The firmware closes the socket if nothing talks for too long. So we poll every 10 s, and that also feeds the UI over SSE.
Stale-but-useful. If the spa becomes unreachable, we keep the last known reading and show an “offline” banner. The next poll catches everything up.

What the official app will never do

A real web UI

FastAPI + HTMX + Chart.js (vendored, no CDN, the app lives on the LAN, it has to work if the internet drops). A mobile-first page, a 7-day temperature chart, instant controls. All served by a single uvicorn process on my Mac running 24/7.

A weather-aware scheduler

The Intex app offers a rudimentary timer that isn’t even exposed over the LAN protocol, so I wrote my own. Three primitives: setpoint by time slot, filtration windows, and most importantly “ready by 6 PM” which figures out when to start heating.

The interesting twist: the heating rate isn’t constant. A spa loses heat proportionally to (water − outdoor air). So I pull local weather from Open-Meteo (free, no API key), learn the thermal loss coefficient from the history of heating and cooling phases, and the scheduler automatically shifts the start time earlier when it’s cold. If the night will be 4 °C, we start heating 90 min ahead; if it’s 18 °C, 30 min is enough.

A camera with cover detection (experimental)

The spa is partly visible in the field of an outdoor IP camera. I plugged in ffmpeg to grab a frame every 10 s, write it atomically (tmp + replace), rebuild a daily mp4 timelapse on the fly, and (for kicks) detect whether the cover is on via a calibratable ROI and a luma + std-dev heuristic. It’s partial and flaky at night, so it isn’t wired into the scheduler in v1. But the plumbing is there for the day it is.

A launchd service that survives silent failures

This is the part that took me the longest and that nobody talks about. On this machine, CPython 3.14 was silently killing the service after ~30 s under launchd. No traceback, no log, just a dying process. Culprit: a segfault in uvloop / httptools / pydantic-core on long loops. Back to 3.12, problem gone. And then all the plist settings you only learn the hard way: ThrottleInterval=15 to avoid respawn loops that saturate launchd, ProcessType=Adaptive (not Background, otherwise jetsam kills us first under memory pressure), ExitTimeOut=20 to let the TCP connection close cleanly, and crucially no --workers 1 on uvicorn (that flag flips it into multiprocess mode and wedges under launchd; the default single-process does exactly what you want).

Stack

Python 3.12 + FastAPI + HTMX + Chart.js + ffmpeg + Open-Meteo + launchd + ngrok for remote access. No database: the whole state fits in a handful of JSON and JSONL files under state/. 135 offline tests that run in 3 seconds without touching the real spa (a fake_spa.py replays the protocol).

The reusable pattern

This black box looks like every other one: a low-end IoT device that demands a cloud account to do the most trivial job. The pattern works for Tuya bulbs, Somfy shutters, and probably half the things in your house too:

Find the open TCP port on the LAN (an nmap usually does it).
Capture a few exchanges with Wireshark from the official app.
Identify the checksum and framing (protocol docs are rarely public, but rarely complicated either).
Rewrite a minimal client, validate byte-for-byte, add what the vendor never wanted to build.
Block the device’s WAN egress at the router, end of phone-home.

The code is public, now split across two repositories: github.com/sxnlabs/onsen-server for the FastAPI service and spa protocol, and github.com/sxnlabs/onsen-app for the application. Permissive licenses. If you have a PureSpa Baltik, you can literally fork the server and install it. And if you have another device with the same pattern, read intex_spa/protocol.py on the server side, it’s a good template for starting your own.

If you have one of these at work

I run into this black-box situation regularly on the consulting side: an industrial machine with an undocumented API, a sensor stuck behind a cloud app that bottlenecks the whole team, a B2B home-automation integration the vendor won’t build. That’s the kind of thing I unblock at SXN Labs. If you have a device that should just talk to your stack, drop me a line.

Setup Scaleway Object Storage for Rails Active Storage

2025-05-07T15:00:00+02:00

Scaleway provides an object storage service compatible with the S3 API.

Here’s how to configure your bucket via Terraform, though you can also do it directly through the console.

Table of contents:

IAM Permissions Management
Bucket Creation
Ruby on Rails Configuration

Note: the var.scw_project variable contains your project UUID, which you can find in the console.

IAM Permissions Management

First, we’ll create an application to which we’ll assign permissions and from which we’ll retrieve the key pair for authentication.

Here, I’m granting full permissions (ObjectStorageFullAccess) for the Object Storage API, but you can be more restrictive if you prefer.

# iam.tf

resource "scaleway_iam_application" "my_app" {
  name        = "MyApp"
  description = "MyApp application"
}

resource "scaleway_iam_api_key" "my_app" {
  application_id     = scaleway_iam_application.my_app.id
  description        = "MyApp API Key"
  default_project_id = var.scw_project
}

resource "scaleway_iam_policy" "my_app_object_storage" {
  name           = "MyApp Object Storage"
  description    = "Gives MyApp full access to object storage"
  application_id = scaleway_iam_application.my_app.id

  rule {
    project_ids          = [var.scw_project]
    permission_set_names = ["ObjectStorageFullAccess"]
  }
}

Add the outputs below to retrieve the authentication key pair:

# outputs.tf

output "my_app_access_key" {
  value     = scaleway_iam_api_key.my_app.access_key
  sensitive = true
}

output "my_app_secret_key" {
  value     = scaleway_iam_api_key.my_app.secret_key
  sensitive = true
}

Bucket creation

Let’s move on to creating the bucket. I’ve added rules to migrate objects between storage classes, but you’re not required to use them. CORS rules are important if you want to use direct uploads.

# object_storage.tf

resource "scaleway_object_bucket" "my_app" {
  name       = "my_app"
  region     = "fr-par"
  project_id = var.scw_project

  tags = {
    "Application" = "MyApp"
  }

  lifecycle_rule {
    id                                     = "abort_incomplete_multipart_upload"
    enabled                                = true
    abort_incomplete_multipart_upload_days = 7
  }

  lifecycle_rule {
    id      = "onezone_ia"
    enabled = true

    transition {
      days          = 30
      storage_class = "ONEZONE_IA"
    }
  }

  lifecycle_rule {
    id      = "glacier"
    enabled = true

    transition {
      days          = 120
      storage_class = "GLACIER"
    }
  }

  cors_rule {
    allowed_methods = ["GET", "HEAD", "POST", "PUT", "DELETE"]
    allowed_headers = ["*"]
    allowed_origins = [
      "*"
    ]
    expose_headers  = ["ETag"]
    max_age_seconds = 3600
  }
}

The last thing we need to configure here is the bucket policy to ensure that the application can access it. Note that I’ve also added a rule for my own user so I can still access the bucket from the console.

# object_storage.tf

resource "scaleway_object_bucket_policy" "my_app" {
  bucket = scaleway_object_bucket.my_app.name

  policy = jsonencode({
    Id      = "my_app",
    Version = "2023-04-17",
    Statement = [
      {
        Effect    = "Allow"
        Action    = ["*"]
        Principal = { SCW = "application_id:${scaleway_iam_application.my_app.id}" }
        Resource = [
          scaleway_object_bucket.my_app.name,
          "${scaleway_object_bucket.my_app.name}/*",
        ]
      },
      {
        Effect    = "Allow"
        Action    = ["*"]
        Principal = { SCW = "user_id:${var.scw_my_user}" }
        Resource = [
          scaleway_object_bucket.my_app.name,
          "${scaleway_object_bucket.my_app.name}/*",
        ]
      }
    ]
  })
}

Ruby on Rails Configuration

We can now configure Active Storage with our setup.

# config/storage.yml

scaleway:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:scaleway, :access_key) %>
  secret_access_key: <%= Rails.application.credentials.dig(:scaleway, :secret_key) %>
  region: fr-par
  bucket: my_app
  endpoint: https://s3.fr-par.scw.cloud

Retrieve the key pair using the commands below:

tf output my_app_access_key
tf output my_app_secret_key

And that’s it!

Upgrade your Rails app from esbuild to import-maps

2023-11-10T11:00:00+02:00

The import-maps gem finally allows us to get rid of JavaScript tooling in our Ruby on Rails projects, whether it’s esbuild or webpacker.

Let’s see together how to convert a project using esbuild, in my case, to import-maps.

Initial State

Our layout links the application.js and application.css files.

# views/layouts/application.html.erb
<head>
  <!-- ... -->
  <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
  <%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>
</head>

The CSS file imports styles from various NPM packages located in the node_modules directory as well as TailwindCSS directives.

@import "notyf/notyf.min";
@import "trix/dist/trix";
@import "actiontext.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

And the JS file imports different packages as well as our Stimulus controllers.

import "@hotwired/turbo-rails";
import "trix";
import "@rails/actiontext";
import "./controllers";

A setup that couldn’t be more classic.

Installing `import-map`

If your app wasn’t created with Rails 7+, run the commands below to install the gem.

$ bundle add importmap-rails

Then:

$ bundle exec rails importmap:install

You will find the new importmap.rb file in the config directory, which somewhat replaces the package.json file that read our NPM dependencies.

There, you’ll find a list of pins.

Packages can be loaded from several sources:

A URL: pin "notyf", to: "https://ga.jspm.io/npm:notyf@3.10.0/notyf.es.js"
A gem: pin "@hotwired/turbo-rails", to: "turbo.min.js"
A local file: pin "application"
A local directory: pin_all_from "app/javascript/controllers", under: "controllers"

Update

The import-map installation has already prefilled the importmap.rb file for you.

You should find there the @hotwired/stimulus-loading pin, which is a new method of loading for Stimulus controllers that doesn’t require manually registering them.

You can now pin 🍆 your NPM packages to include them in the import list.

$ ./bin/importmap pin notyf

This command will automatically add all the dependencies of the notyf package.

Here’s the list of pins for me:

# config/importmap.rb
pin "application", preload: true
pin "i18n", preload: true
pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true
pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
pin_all_from "app/javascript/utils", under: "utils"
pin_all_from "app/javascript/controllers", under: "controllers"
pin "trix"
pin "@rails/actioncable", to: "https://ga.jspm.io/npm:@rails/actioncable@7.1.1/app/assets/javascripts/actioncable.esm.js"
pin "@rails/actiontext", to: "actiontext.js"
pin "notyf", to: "https://ga.jspm.io/npm:notyf@3.10.0/notyf.es.js"

You can now modify your layout to load the import-maps.

# views/layouts/application.html.erb
<head>
  <!-- ... -->
  <%= stylesheet_link_tag "trix",
  <%%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>

  <%= javascript_importmap_tags %>
</head>

“We are now loading CSS files manually and one by one, to avoid having a single large bundle and to leverage the capabilities of HTTP 2 for loading multiple files quickly.

Cleanup

You can now delete all the files related to JavaScript tooling:

$ rm -rf package.json yarn.lock node_modules

Welcome to a rational world without all the complexity of frontend tools! 🥳

If you want to react to this article or need assistance with updating your Ruby on Rails applications, contact me on LinkedIn, Mastodon.”

Control and document the variables of Ruby on Rails partials

2023-11-09T11:40:00+02:00

The partials in Ruby on Rails can quickly become a nightmare to manage because the only way to have the list of variables (locals in Rails jargon) used by a partial is to directly read its source code, which often contains several hundred lines of HTML code…

Since the release of Ruby on Rails 7.1, it is possible to use magic comments at the top of your partials to constrain and document the use of locals in that partial.

Let’s see right away how this works. 👏

Let’s start by defining the partial’s variables as follows:

# app/views/users/_user_card.html.erb


My name is <%= name %>
Reach me at <%= email %>

Then, we pass these variables from the template in the locals hash.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full,
    email: @user.email
  }
%>

As defined, the variables name and email are mandatory, and their absence will cause an error.

Let’s remove the email variable to see what happens.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full
  }
%>

An error is immediately raised.

ActionView::Template::Error (missing local: :email):

app/views/users/show.html.erb:1

Now, let’s try to pass an undefined variable.

# app/views/users/show.html.erb

<%= render partial: "user_card",
  locals: {
    name: @user.name.full,
    email: @user.email,
    phones: @user.phones
  }
%>

A new error is raised, this time to tell us that this variable is not accepted because it was not declared in the partial.

ActionView::Template::Error (unknown local: :phones):

app/views/users/show.html.erb:1

Thanks to these two errors, we are now certain of the variables accepted by our partial and we have at the same time gained a bit of documentation! 🎉

Default Values

It is possible to give default values to variables, which will allow us not to have to pass them each time we render.

# app/views/users/_user_card.html.erb


My name is <%= name %>
Reach me at <%= email %>
You can also give me a call at <%= phones.join(", ") %>

This way, it is possible not to provide the phones variable to the partial without the call to the join method failing, because it has been called on nil.

Disabling Variables

If you do not want any variables to be passed to your partial, this is also possible!

# app/views/users/_user_card.html.erb


My name is John
Reach me at john@doe.com
You can also give me a call at 0123456789

If we attempt to pass variables during rendering, the error below will be raised.

ActionView::Template::Error (no locals accepted):

app/views/users/show.html.erb:1

That concludes our little tour of this new feature in Rails 7.1, allowing us to exercise better control over the variables passed to our partials while documenting them.

Manage Your Ruby Processes with Overmind

2023-11-03T16:30:00+02:00

Ruby on Rails 7 has introduced a new executable bin/dev. It won’t be present by default unless you create a new application with the --css option or run the css:install command.

This file calls the Foreman Gem which, in turn, executes the processes defined in the Procfile.dev at the root of your project.

This way of operating allows you to launch as many processes as you want in parallel, with a single command.

Here is an example of a Procfile from one of my projects.

web: bin/rails server -p 3000
css: bin/rails tailwindcss:watch
worker: bundle exec good_job start
guard: bundle exec guard
stripe: stripe listen --forward-to localhost:3000/pay/webhooks/stripe

All this works perfectly until the moment you need to debug your application with breakpoints. Foreman does not allow you to access the debug console of a particular process.

This is where Overmind comes into play. This program does exactly the same thing as Foreman while allowing you to connect to your processes.

Install Overmind on your machine as follows:

# on macOS (with homebrew)
$ brew install tmux

# on Ubuntu
$ apt-get install tmux

Then start your processes:

$ overmind s -f Procfile.dev

I will now put a breakpoint in a Rails controller of the web process.

class HomeController < ApplicationController
  def index
    debugger
    # ...
  end
end

From another terminal, but in the same directory (where your Procfile.dev is located), run the following command:

$ overmind c web

You can now access the Ruby console! 🎉

Of course, this feature is not limited to Ruby and works with any program/language.