React 18 Streaming. Made fully-fledged & easy.


Features (for React users):

  • Unlocks <Suspsense> for SSR apps.
  • Unlocks React libraries of tomorrow. (Such as using Telefunc for data fetching.)
  • Supports all platforms (Vercel, Cloudflare Workers, AWS, Netlify Edge, Deno, Deploy, …).
  • Two SEO modes: conservative or google-bot-speed.
  • Bonus: new useAsync() hook.

Features (for library authors):

  • useSsrData(): Define isomorphic data.
  • injectToStream(): Inject chunks to the stream.


import { renderToStream } from 'react-streaming/server'

const {
  pipe, // Node.js (Vercel, AWS)
  readable // Edge Platforms (Coudflare Workers, Netlify Edge, Deno Deploy)
} = await renderToStream(<Page />)

Why Streaming

React 18’s new SSR streaming architecture unlocks many capabilities:

  • Data Fetching:
    • Use RPC to fetch data in a seamless way, e.g. with Telefunc or tRPC. (Data fetching SSR hooks will be a thing of the past: no more Next.js’s getServerSideProps() nor vite-plugin-ssr‘s onBeforeRender().)
    • Expect your GraphQL tools to significantly improve, both performance and DX. (Also expect new tools such as Vilay.)
  • Fundamentally improved mobile performance. (Mobile users can progressively load the page as data is fetched, before even a single line of JavaScript is loaded. Especially important for low-end and/or poorly-connected devices.)
  • Progressive Hydration. (Page is interactive before the page/data finished loading.)

The problem: The current React 18 Streaming architecture is low-level and its ergonomics are cumbersome. (E.g. there is no standard way for library authors to take advantage of the new streaming architecture.)

The solution: react-streaming.

Get Started

  1. Install

    npm install react-streaming
  2. Server-side

    import { renderToStream } from 'react-streaming/server'
    // Cross-platform
    const {
      pipe, // Defined if running in Node.js, otherwise `null`
      readable // Defined if running in Edge Platforms (.e.g. Coudflare Workers), otherwise `null`
    } = await renderToStream(<Page />, options)
  3. Client-side

    import { ReactStreaming } from 'react-streaming/client'
    // Wrap your root component `<Page>` (aka `<App>`) with `<ReactStreaming>`
    const page = (
        <Page />


  • options.disable?: boolean: Disable streaming.

    The component is still rendered to a stream, but the promise const promise = await renderTo... resolves only after the stream has finished. (This effectively disables streaming from a user perspective, while unlocking React 18 Streaming capabilities such as SSR <Supsense>.)

  • options.seoMode?: 'conservative' | 'google-bot-speed'

    • conservative: Disable streaming if the HTTP request originates from a bot. (Ensuring the bot always sees the whole HTML.)

    • google-bot-speed: Don’t disable streaming for the Google Bot.

      • Pro: Google ranks your website higher because the initial HTTP response is faster. (To be researched.)
      • Con: Google will likely not wait for the whole HTML, and therefore not see it. (To be tested.)
    • Custom SEO strategy: use options.disable. For example:

      // Always stream, even for bots:
      const disable = false
      // Disable streaming for bots, except for the Google Bot and some other bot:
      const disable =
        isBot(userAgent) &&
        !['googlebot', 'some-other-bot'].some(n => userAgent.toLowerCase().includes(n))
      const stream = await renderToStream(<Page />, { disable })
  • options.userAgent?: string: The HTTP User-Agent request header. (Needed for seoMode.)

Bonus: useAsync()

import { useAsync } from 'react-streaming'

function StarWarsMovies() {
  return (
      <p>List of Star Wars movies:</p>
      <Suspense fallback={<p>Loading...</p>}>
        <MovieList />

// This component is isomorphic: it works on both the client-side and server-side.
// The data fetched while SSR is automatically passed and re-used on the client for hydration.
function MovieList() {
  const movies = useAsync(async () => {
    const response = await fetch('')
    return response.json()
  return (
      {movies.forEach((movie) => (
          {movie.title} ({movie.release_date})

Get Started (Library Authors)

react-streaming enables you to suspend React rendering and await something to happen. (Usually data fetching.) The novelty here is that it’s isomorphic:

  • It works on the client-side, as well as on the server-side (while Serve-Side Rendering).
  • For hydration, data is passed from the server to the client. (So that data isn’t loaded twice.)

You have the choice between three methods:

  • useAsync(): Highest-level & easiest.
  • useSsrData(): High-level & easy.
  • injectToStream(): Low-level and highly flexible (both useAsync() and useSsrData() are based on it). Easy & recommended for injecting script and style tags. Complex for data fetching (if possible, use useSsrData() or useAsync() instead).


For how to use useAsync(), see example above.


import { useSsrData } from 'react-streaming'

function SomeComponent() {
  const key = 'some-unique-key'
  const someAsyncFunc = async function () {
    return 'someData'
  // `useSsrData()` suspends rendering until the promise returned by `someAsyncFunc()` resolves.
  const value = useSsrData(key, someAsyncFunc)
  // `value` is the value returned by `someAsyncFunc()`.
  assert(value === 'someData')

If <SomeComponent> is rendered only on the client-side, then useSsrData() is essentially a cache that never invalidates. (If you want to re-run someAsyncFunc(), then change the key.)

If <SomeComponent> is rendered on the server-side (SSR), it injects the resolved value into the stream and the client-side picks up the injected value. (So that the client-side doesn’t call someAsyncFunc() but, instead, re-uses the value resolved on the server-side.)

This is for example how useAsync() is implemented:

import { useId } from 'react'
import { useSsrData } from 'react-streaming'

function useAsync(asyncFn) {
  const id = useId()
  return useSsrData(id, asyncFn)


injectToStream(htmlChunk: string) allows you to inject strings to the current stream.

There are two ways to access injectToStream():

  1. With renderToStream():

    import { renderToStream } from 'react-streaming/server'
    const { injectToStream } = await renderToStream(<Page />)
  2. With useStream():

    import { useStream } from 'react-streaming'
    function SomeComponent() {
      const stream = useStream()
      if (stream === null) {
        // No stream available. This is the case:
        // - On the client-side.
        // - When `option.disable === true`.
        // - When react-streaming is not installed.
      const { injectToStream } = stream

Usage examples:

// Inject JavaScript (e.g. for progressive hydration)
injectToStream('<script type="module" src="/main.js"></script>')

// Inject CSS (e.g. for CSS-in-JS)
injectToStream('<styles>.some-component { color: blue }</styles>')

// Pass data to client
injectToStream(`<script type="application/json">${JSON.stringify(someData)}</script>`)

For a full example of using injectToStream(), have a look at useSsrData()‘s implementation.


View Github