---
title: Turbo n'a pas trois outils, il a trois portées
description: 'Drive, Frames, Streams et morphing expliqués par ce qui les relie :
qui désigne la cible du remplacement. Avec les pièges que la documentation officielle
ne mentionne pas, et un index par symptôme.'
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 portées
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 seule question qui compte au moment d'écrire : lequel, ici, maintenant.
Il y a une réponse, et elle est simple. Turbo ne fait qu'une chose : il intercepte une navigation, récupère du HTML, et remplace une portion du document. Drive, Frames et Streams ne sont pas trois mécanismes, ce sont trois **portées** de ce remplacement, qui se distinguent par une seule variable : qui désigne la cible.
Ce qui suit est ce que j'aurais voulu lire il y a trois ans. C'est long, c'est fait pour être relu par morceaux, et ça se termine par un index qui part du symptôme observable. Les versions de référence sont **Turbo 8.0.23** et **turbo-rails 2.0.23**, toutes deux publiées le 29 janvier 2026, sur Rails 8.
## Le modèle en une page
La même mécanique, trois portées. La seule variable qui change est celle qui désigne la cible.
Avec **Drive**, la cible est implicite : c'est le ``. 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 qui émet met son identifiant dans un en-tête `Turbo-Frame`, et Turbo n'acceptera de la réponse que l'élément portant le même identifiant. Le serveur ne choisit rien : il subit une contrainte.
Avec **Streams**, la cible est écrite dans la réponse. Le serveur 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.
Tout le reste découle de ça. Un frame qui ne se met pas à jour, c'est presque toujours un identifiant qui ne correspond pas. Un stream qui n'a aucun effet, c'est presque toujours une cible absente du DOM. Le morphing, qu'on verra plus loin, ne change pas ce modèle : il change seulement *comment* le remplacement est appliqué, pas *qui* le décide.
## 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 sur les `` de même origine et les soumissions de formulaires. Il **n'intercepte pas** : les liens avec un attribut `target` autre que `_self`, les liens `download`, les URL cross-origin, et les URL dont l'extension figure dans `Turbo.config.drive.unvisitableExtensions` (une cinquantaine d'extensions, dont `.pdf`, `.zip`, `.csv`, `.jpg`). Cette dernière liste est configurable et n'est documentée nulle part sur le site officiel.
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 réactive.
### Le cycle de vie
Les cases en pointillés ne sont pas des événements : ce sont les étapes internes que les événements encadrent.
Deux points méritent qu'on s'y arrête, parce qu'ils expliquent une bonne moitié des bugs de cycle de vie.
**L'instantané est pris de la page qu'on quitte, pas de celle qu'on charge.** `turbo:before-cache` se déclenche sur le document vivant, juste avant que Turbo n'en fasse un `cloneNode(true)`. C'est donc votre dernière chance de défaire ce que votre JavaScript a ajouté au DOM. Et il y a une asymétrie cruelle : le clone **perd les écouteurs d'événements** mais **garde le DOM injecté**. C'est exactement la recette de la bibliothèque initialisée deux fois au retour arrière, qu'on verra plus loin.
Détail utile : le clone remet aussi la sélection des `