React 18:n suoratoisto: renderToPipeableStreamin toiminta

Ennen React 18:aa palvelinrenderöinnissä käytettiin renderToStringia, joka on synkroninen: React renderöi koko komponenttipuun merkkijonoksi ennen minkään HTML:n lähettämistä selaimeen. Jos jokin komponentti lataa tietoja, palvelimen on odotettava kaikkien tietojen valmistumista, ennen kuin ensimmäinen tavu saavuttaa käyttäjän.

React 18 toi käyttöön renderToPipeableStreamin, joka renderöi komponenttipuun HTML-palasten virtana. Sen sijaan että React odottaisi kaiken valmistumista, se lähettää HTML:ää sitä mukaa kuin puun osat valmistuvat, jolloin selain voi aloittaa näkyvän sisällön renderöinnin heti.

renderToPipeableStream palauttaa olion, jossa on kaksi metodia: pipe(writable) ja abort(). pipe vastaanottaa Node.js Writable -streamin (tyypillisesti HTTP-vastauksen) ja aloittaa HTML:n streamauksen siihen. abort() peruuttaa streamin, ja sitä käytetään, kun pyyntö peruutetaan tai aikakatkaisu ylittyy.

Stream alkaa HTML-shellistä eli kaikesta sisällöstä, jota odottava Suspense-rajaus ei estä. Tähän kuuluvat dokumentin head, navigaatio, alatunniste, layoutin rakenteet ja kaikki synkronisesti saatavilla oleva sisältö. Shell streamataan heti, ennen kuin mitkään tiedoista riippuvaiset komponentit valmistuvat.

Suspense-rajausten sisällä olevat tietoja odottavat komponentit streamataan aluksi fallback-UI:na (esimerkiksi latausspinnerinä). React lähettää myöhemmin script-tagin, joka korvaa fallbackin valmiilla sisällöllä — ilman shellin uudelleenrenderöintiä clientillä.

Välitä renderToPipeableStreamille bootstrapScripts: ['/static/js/client.js'], jotta React lisää script-tagin streamin loppuun. Selain lataa tämän bundlen ja kutsuu hydrateRootia, joka liittää Reactin tapahtumankäsittelijät palvelimella renderöityyn DOM:iin.

onShellReady suoritetaan, kun HTML-shell (kaikki odottavien Suspense-rajausten ulkopuolinen sisältö) on valmis lähetettäväksi. Tällöin on oikea hetki kutsua pipe(res)-metodia — mutta HTTP-statuskoodi ja vastauksen otsakkeet on tärkeää asettaa ennen pipe-kutsua, koska streamaus lukitsee HTTP-statuksen.

Koska streamaus alkaa heti, kun kutsutte pipe()-funktiota, kaikkien res.setHeader- tai res.statusCode-määritysten on tapahduttava ennen pipe()-kutsua. Yleinen käytäntö on asettaa tilakoodiksi 200 ja Content-Type: text/html -otsakkeeksi onShellReady-callbackissa ja kutsua heti sen jälkeen pipe(res)-funktiota.

onShellError suoritetaan, kun ennen shellin renderöinnin valmistumista tapahtuu virhe, josta ei voida palautua — esimerkiksi kun ylätason komponentti aiheuttaa poikkeuksen Suspense-rajan ulkopuolella. Tällöin osittaista vastausta ei voi streamata. Ohjatkaa käyttäjä sen sijaan virhesivulle tai lähettäkää staattinen HTML-virhedokumentti.

onAllReady suoritetaan, kun koko React-puu on valmis — myös kaikki Suspense-rajat. Hakukoneiden indeksointiroboteille ja sosiaalisen median linkkien esikatseluille kannattaa lähettää valmis HTML ilman streamausta. Tarkistakaa, onko pyyntö peräisin botilta, ja kutsukaa pipe(res)-funktiota onAllReady-tapahtumassa onShellReady-tapahtuman sijaan.

onError suoritetaan Suspense-rajoissa tapahtuvien virheiden yhteydessä. React pystyy silti streamaamaan muun sivun, kun kyseinen raja näyttää virhenäkymän. Käyttäkää onError-funktiota virheen kirjaamiseen observability-putkeen keskeyttämättä käyttäjän streamausta.

renderToPipeableStream on React 18:n Node.js-palvelimille tarkoitettu streamaavan SSR:n perusratkaisu. Se streamaa HTML-shellin heti onShellReady-tapahtuman kautta, täydentää Suspense-rajoja datan valmistuessa ja hydratoi asiakkaan bootstrapScripts-määrityksen avulla. Käyttäkää onAllReady-tapahtumaa boteille ja indeksoijille, onShellError-tapahtumaa kriittisiin virheisiin ja määrittäkää HTTP-otsakkeet aina ennen pipe()-funktion kutsumista.