Streaming dans React 18 : fonctionnement de renderToPipeableStream

Avant React 18, le rendu côté serveur utilisait renderToString, qui est synchrone : React rend l’arbre complet des composants sous forme de chaîne avant d’envoyer le moindre HTML au navigateur. Si un composant charge des données, le serveur doit attendre toutes les données avant que le premier octet n’atteigne l’utilisateur.

React 18 a introduit renderToPipeableStream, qui rend l’arbre des composants sous forme de flux de fragments HTML. Au lieu d’attendre que tout soit prêt, React envoie le HTML au fur et à mesure que chaque partie de l’arbre est terminée, ce qui permet au navigateur de commencer immédiatement le rendu du contenu visible.

renderToPipeableStream renvoie un objet doté de deux méthodes : pipe(writable) et abort(). pipe accepte un flux Writable de Node.js (généralement la réponse HTTP) et commence à y diffuser le HTML. abort() annule le flux : cette méthode est utilisée lorsque la requête est annulée ou qu’un délai d’attente est dépassé.

Le flux commence par la coquille HTML — tout le contenu qui n’est pas bloqué par une limite Suspense en attente. Cela comprend l’en-tête du document, la navigation, le pied de page, la structure visuelle de la mise en page et tout contenu disponible de manière synchrone. La coquille est diffusée immédiatement, avant la résolution des composants dépendant des données.

Les composants situés dans des limites Suspense et en attente de données sont d’abord diffusés avec leur interface de remplacement (par exemple, un indicateur de chargement). React envoie ensuite une balise script qui remplace l’interface de remplacement par le contenu résolu — sans nouveau rendu côté client de la coquille.

Transmettez bootstrapScripts: ['/static/js/client.js'] à renderToPipeableStream pour indiquer à React d’injecter une balise script à la fin du flux. Le navigateur charge ce paquet et appelle hydrateRoot, en associant les gestionnaires d’événements de React au DOM rendu par le serveur.

onShellReady est exécutée lorsque la coquille HTML (tout ce qui se trouve en dehors des limites Suspense en attente) est prête à être envoyée. C’est le bon moment pour appeler pipe(res) — mais, point important, définissez le code d’état HTTP et les en-têtes de réponse avant d’appeler pipe, car le flux fixe définitivement le code d’état HTTP.

Comme le lancement du flux commence immédiatement lorsque vous appelez pipe(), toute affectation à res.setHeader ou res.statusCode doit avoir lieu avant l'appel à pipe. Un schéma courant consiste à définir le statut 200 et Content-Type: text/html dans le rappel onShellReady, puis à appeler immédiatement pipe(res).

onShellError se déclenche lorsqu'une erreur irrécupérable survient avant la fin du rendu de la structure initiale — par exemple, lorsqu'un composant de niveau supérieur lève une erreur en dehors de toute limite Suspense. Dans ce cas, vous ne pouvez pas diffuser une réponse partielle ; redirigez plutôt vers une page d'erreur ou envoyez un document HTML statique d'erreur.

onAllReady se déclenche lorsque tout l'arbre React est résolu — y compris toutes les limites Suspense. Pour les robots des moteurs de recherche et les générateurs d'aperçus de liens des réseaux sociaux, vous devez envoyer le HTML complet sans diffusion en flux. Vérifiez si la requête provient d'un robot et appelez pipe(res) dans onAllReady plutôt que dans onShellReady.

onError se déclenche en cas d'erreurs dans les limites Suspense — React peut continuer à diffuser le reste de la page pendant que cette limite affiche son interface d'erreur de secours. Utilisez onError pour consigner l'erreur dans votre chaîne d'observabilité sans interrompre le flux pour l'utilisateur.

Quand devez-vous utiliser onAllReady plutôt que onShellReady pour commencer à appeler pipe ?

renderToPipeableStream est la primitive de SSR en flux de React 18 pour les serveurs Node.js. Elle diffuse immédiatement la structure HTML via onShellReady, complète les limites Suspense au fur et à mesure de la résolution des données et hydrate le client via bootstrapScripts. Utilisez onAllReady pour les robots et les robots d'exploration, onShellError en cas d'échec fatal et définissez toujours les en-têtes HTTP avant d'appeler pipe().