--- title: Turbo n’a pas trois outils, il a trois scopes description: Une grille simple pour choisir entre Drive, Frames et Streams, puis diagnostiquer le cache, le morphing et les broadcasts dans Turbo 8.0.23. url: https://sxnlabs.com/ruby/2026/08/06/turbo-drive-frames-streams-reference/ lang: fr date: '2026-08-06T09:00:00+02:00' tags: - Hotwire - Turbo - Rails - Morphing - Stimulus --- # Turbo n’a pas trois outils, il a trois scopes La documentation de Turbo a la réputation d'être incomplète. Elle ne l'est pas vraiment : chaque page dit à peu près ce qu'elle doit dire. Le problème est ailleurs. Drive, Frames et Streams y sont documentés côte à côte, comme trois produits distincts, sans que rien ne dise ce qui les relie ni comment choisir. On apprend la syntaxe de chacun, et on reste bloqué sur la question qui compte au moment d'écrire : lequel, ici, maintenant. Pour choisir, je regarde deux choses : **la portion du document qui change** et **le moment où sa cible est décidée**. Drive vise implicitement la page entière. Un frame nomme son fragment avant l'envoi de la requête. Un stream laisse le serveur désigner ses cibles dans la réponse. Cette lecture donne trois **périmètres** de mutation : la page entière, un fragment nommé, ou un ensemble d'éléments désignés dans une réponse. `remove`, `refresh`, les actions personnalisées et les broadcasts ne sont pas littéralement des remplacements, mais la grille reste utile. Le morphing change la manière d'appliquer la mutation, pas son périmètre. J'aurais aimé disposer de cette grille il y a trois ans. Le modèle et le tableau suffisent pour choisir ; la checklist et l'index servent au diagnostic. Le reste documente Turbo 8.0.23. ## Versions et niveau de garantie Cet article cible **Turbo 8.0.23** et **turbo-rails 2.0.23**, publiés le 29 janvier 2026, avec Rails 8. Les détails ci-dessous viennent surtout du code et des tests de ces versions épinglées. Les encadrés qui s'appuient sur une garantie particulière utilisent les étiquettes suivantes : Les liens vers le code de Turbo et turbo-rails pointent sur les tags `v8.0.23` et `v2.0.23`, donc sur des lignes figées : elles diront toujours ce que je leur fais dire, même quand la branche `main` aura bougé. ## Le modèle en une page
Trois panneaux comparant Turbo Drive qui remplace la page entière, Turbo Frames qui remplace un fragment désigné par le client avant l'envoi de la requête, et Turbo Streams qui applique des ordres à des cibles nommées par le serveur dans la réponse.
La même mécanique, trois scopes. Ce qui change d'une colonne à l'autre : l'étendue du remplacement, qui en désigne la cible, et à quel moment.
Avec **Drive**, la cible est implicite : c'est le ``. Elle n'est jamais négociée, il n'y a donc aucun contrat d'identifiant à respecter. Le client décide de naviguer, le serveur répond une page, Turbo échange le corps et fusionne l'en-tête. Avec **Frames**, la cible est décidée par le client **avant même que la requête parte**. Le frame à l'origine de la requête envoie son identifiant dans le header `Turbo-Frame`. Sur le chemin d'extraction normal, Turbo n'accepte que l'élément portant ce même identifiant, directement ou au bout d'un frame `recurse`. Le serveur ne peut pas rediriger le contenu vers un autre frame. Il peut seulement court-circuiter l'extraction avec `turbo-visit-control: reload`, qui transforme la réponse en visite pleine page. Avec **Streams**, la cible est écrite **dans la réponse**, donc décidée au dernier moment, par le serveur. Il dit `remplace l'élément qui a cet id`, `ajoute ceci à la fin de celui-là`, `supprime cet autre`. Il peut viser plusieurs endroits non contigus, et il peut le faire sans que personne n'ait rien demandé, via un WebSocket. > **À retenir**{: .callout-label} > > Deux des trois primitives passent un contrat avec le DOM. Pour un frame, le chemin d'extraction normal doit trouver l'identifiant attendu, directement ou via `recurse` ; sinon Turbo émet `turbo:frame-missing` puis, par défaut, affiche « Content missing » et lève une erreur. Un listener peut annuler l'événement pour prendre le relais. `turbo-visit-control: reload` contourne entièrement ce chemin avec une visite pleine page. Pour un stream, le contrat est *la cible doit exister dans le document au moment où l'ordre arrive* ; une cible absente est, elle, un no-op silencieux. {: .callout .callout-retenir} ## Quelle primitive choisir ? Le tableau ci-dessous est la version courte. Il ne classe pas les outils du plus simple au plus avancé. Partez de l'origine de l'état, puis choisissez la première ligne qui décrit réellement le besoin. | Votre besoin | La primitive | Pourquoi ce choix | |---|---|---| | L'état est purement client et le serveur n'a rien à en savoir | **Stimulus, sans Turbo** | Un aller-retour réseau pour ouvrir un menu est un aller-retour de trop | | L'URL et la page entière représentent le nouvel état | **Drive**, c'est-à-dire rien à écrire | C'est déjà actif et fournit l'historique ainsi que le bouton retour | | Une seule zone change, et une URL répond avec un `` de même identifiant | **Frame** | Turbo gère nativement le lazy loading (`loading="lazy"`), le loading state et la navigation interne. `data-turbo-action` peut promouvoir cette navigation dans l'historique | | Plusieurs zones non contiguës changent en réponse à une action de l'utilisateur | **Réponse `.turbo_stream`** | Un frame ne peut viser qu'un fragment. Découper la page en cinq frames pour simuler un stream multiplie les requêtes | | Le changement doit atteindre un navigateur qui n'a pas lancé la requête courante | **Broadcast** | Le destinataire n'a pas de réponse HTTP à appliquer. Lorsque Turbo rend lui-même le HTML du broadcast, son renderer synthétique n'a ni session ni `current_user` exploitable | Reste le cas où les deux semblent possibles. **Le test de l'URL, pour les frames.** S'il n'existe pas d'URL dont la réponse contient ce fragment sous un `` de même identifiant, ce n'est probablement pas un frame que vous voulez. Un frame est un contexte de navigation : les liens et formulaires qu'il capture ont une URL et un loading state ; l'historique reste optionnel via `data-turbo-action`. **Le test du destinataire, pour les streams.** Si seul l'onglet qui vient d'agir doit changer, c'est une réponse `.turbo_stream`. Si d'autres onglets doivent recevoir la mutation sans avoir lancé cette requête, c'est un broadcast. Ce sont deux usages très différents qui partagent un format, et les confondre est une source classique de HTML diffusé au mauvais utilisateur. ## Turbo Drive Drive est actif dès que vous chargez `@hotwired/turbo`. Il n'y a rien à écrire pour en profiter et, contrairement à ce que suggère l'ordre des chapitres de la documentation, c'est là que doit s'arrêter la majorité des besoins. ### Ce qui est intercepté, et ce qui ne l'est pas Drive intercepte les clics principaux sans touche de modification sur les `` navigables, ainsi que les form submissions navigables, tant que leur destination est visitable. Une URL visitable reste sous le `` de la page (`/` par défaut) et son extension ne figure pas dans `Turbo.config.drive.unvisitableExtensions` (une cinquantaine d'extensions, dont `.pdf`, `.zip`, `.csv`, `.jpg`). Les URL cross-origin sont donc exclues avec le `turbo-root` par défaut. Cette liste d'extensions est configurable et n'est documentée nulle part sur le site officiel. Turbo laisse aussi le browser gérer les liens `download`, tous les liens dont `target` diffère de `_self`, ainsi que les formulaires en `method="dialog"`. Vous coupez ponctuellement avec `data-turbo="false"` sur l'élément ou n'importe lequel de ses ancêtres. Un `data-turbo="true"` imbriqué plus bas le réactive. ### Le cycle de vie Il n'existe pas de séquence universelle. Le tableau suit un link en `advance` qui ouvre une visite Drive avec un fetch. Il suppose que le document de départ est cacheable et qu'aucun snapshot de preview n'existe. Une form submission pleine page effectue d'abord sa propre requête, tandis qu'une restauration depuis le cache saute les événements de fetch. Au chargement initial, `turbo:load` est émis sans `turbo:render`. Les render hooks peuvent aussi s'exécuter deux fois lors d'une preview. La dernière colonne reste la plus utile, parce que plusieurs noms sont trompeurs. | Événement | Émis sur | Annulable | Ce qu'il permet vraiment | |---|---|---|---| | `turbo:click` | le `` cliqué | ✓ | Annuler pour laisser le navigateur faire une navigation classique | | `turbo:before-visit` | `` | ✓ | Le dernier endroit où l'on peut refuser la visite | | `turbo:before-fetch-request` | `` sur une visite, le frame ou le formulaire concerné, le `` sur un prefetch ou un preload | ✓ | `preventDefault()` **ne bloque pas la requête, il la met en pause** jusqu'à l'appel de `detail.resume()` | | `turbo:visit` | `` | ✕ | Informatif. `detail.action` vaut `advance`, `replace` ou `restore` | | `turbo:before-fetch-response` | `` sur une visite, le frame ou le formulaire concerné, le `` sur un prefetch ou un preload | ✓ | Annuler empêche le delegate Visit/Frame/FormSubmission de traiter la réponse. Cela ne bloque pas à lui seul un turbo-stream : `StreamObserver` ignore `defaultPrevented` et peut l'appliquer depuis ce même événement | | `turbo:before-cache` | `` | ✕ | Nettoyer le DOM avant le cache. Le clone est différé au prochain event loop tick | | `turbo:before-render` | `` | ✓ | Même sémantique de pause. `detail.newBody` est modifiable avant rendu, `detail.renderMethod` vaut `replace` ou `morph` | | `turbo:render` | `` | ✕ | Le nouveau corps est en place | | `turbo:load` | `` | ✕ | Fin de la visite. Au premier chargement, Turbo l'émet quand `readystatechange` passe à `interactive` ou `complete` ; un bundle async chargé après `DOMContentLoaded` peut démarrer trop tard et le manquer | Première surprise, **`turbo:before-fetch-request` précède `turbo:visit`**. `Visit#start()` appelle `this.adapter.visitStarted(this)`, qui prépare la requête, **avant** `this.delegate.visitStarted(this)`, qui émet `turbo:visit` ([`visit.js#L114-L118`](https://github.com/hotwired/turbo/blob/v8.0.23/src/core/drive/visit.js#L114-L118)). Le `fetch()` effectif attend encore la fin de l'interception, mais un listener installé depuis `turbo:visit` a déjà manqué `turbo:before-fetch-request`. Instrumentez cet événement directement si vous devez observer ou modifier toutes les requêtes. L'autre surprise tient à un défaut de `dispatch()` : sans `target` explicite, il émet sur `document.documentElement`, pas sur `document` ([`util.js#L29-L44`](https://github.com/hotwired/turbo/blob/v8.0.23/src/util.js#L29-L44)). Avec l'event bubbling, écouter sur `document` fonctionne, mais `event.target` vaut ``, ce qui compte si vous filtrez dessus. C'est le cas des deux événements de fetch d'une visite Drive. Un fetch de frame cible le frame, celui d'une form submission cible le `
`, et ceux du prefetch ou du preload ciblent le ``. Et les événements propres aux frames et aux formulaires, qui s'intercalent dans la même séquence : | Événement | Émis sur | Annulable | Ce qu'il permet vraiment | |---|---|---|---| | `turbo:before-frame-render` | le frame | ✓ | Pause, et `detail.render` est remplaçable : c'est le point d'entrée officiel pour brancher un autre moteur de rendu | | `turbo:frame-render` | le frame | ✕ | Déclaré `cancelable: true`, mais la valeur de retour du dispatch est jetée : l'annuler ne produit rien | | `turbo:frame-load` | le frame | ✕ | Le frame a fini | | `turbo:submit-start` | le `` | ✕ | `detail.formSubmission` | | `turbo:submit-end` | le `` | ✕ | Toujours `detail.formSubmission`. Une réponse traitée par `FormSubmission` ajoute `success` et `fetchResponse` ; une network error ajoute `success: false` et `error`. Ces clés restent absentes après un abort, ainsi qu'après le guard `Form responses must redirect` d'une réponse unsafe 200 non redirigée. | > **Sous le capot**{: .callout-label} vérifié > > `turbo:before-fetch-request` fait une chose de plus que ce que son nom laisse croire. Sa mise en pause est documentée dans le handbook, mais pas le fait que Turbo relise l'URL après coup : `this.url = event.detail.url` ([`fetch_request.js#L183-L199`](https://github.com/hotwired/turbo/blob/v8.0.23/src/http/fetch_request.js#L183-L199)), et c'est bien ce `this.url` qui part au `fetch` juste après. Réécrire `event.detail.url` depuis un listener change donc réellement l'URL appelée, ce qui est le moyen le plus court d'ajouter un préfixe de tenant à toutes les requêtes Turbo d'un coup. > > Encore faut-il **le faire de façon synchrone dans le listener** : l'affectation a lieu *avant* le `await` de la pause, donc modifier `detail.url` après un `preventDefault()` et avant `resume()` n'a aucun effet. Et **affectez un objet `URL`, pas une chaîne** : Turbo lit `this.url.href`, une chaîne donne `undefined`. Ce n'est pas dans le handbook, mais c'est couvert par la suite de tests du dépôt ([`form_submission_tests.js#L191-L204`](https://github.com/hotwired/turbo/blob/v8.0.23/src/tests/functional/form_submission_tests.js#L191-L204)), ce qui en fait une garantie plus solide qu'il n'y paraît. {: .callout .callout-capot} Le reste des bugs de cycle de vie vient presque toujours du snapshot ou de la preview. **Le snapshot vient de la page qu'on quitte, pas de celle qu'on charge.** `turbo:before-cache` se déclenche sur le document courant, puis `PageView#cacheSnapshot()` attend le prochain event loop tick avant le `cloneNode(true)`. Le nettoyage synchrone dans ce hook reste le chemin déterministe. En revanche, la visite n'attend pas la fin de `cacheSnapshot()` : le remplacement du `` et un `disconnect()` Stimulus peuvent donc modifier l'ancien DOM avant le clone. Un `disconnect()` n'arrive pas nécessairement trop tard pour nettoyer le cache. Le clone **perd les listeners** mais **garde le DOM injecté** qui existe encore à cet instant. C'est ainsi qu'une bibliothèque peut se retrouver initialisée deux fois au retour arrière ; on y revient plus loin. Le clone remet aussi la sélection des `