JavaScript and React course ยท Module 10: React Ecosystem and Future

Streaming SSR and Edge Runtime

9 min read ยท
In this lesson8

Imagine that instead of sending the entire spaceship in one transport, you send it module by module - the cockpit immediately, while navigation systems and cargo bays arrive in the background. That is exactly how Streaming SSR works - the server starts sending HTML to the browser before the entire rendering is complete. And Edge Runtime moves this process closer to the user - like relay stations distributed across the galaxy.

Traditional SSR vs Streaming SSR

Traditional SSR generates the entire HTML on the server before sending it to the browser. The user waits for the slowest component:

// Traditional SSR - user waits for EVERYTHING
// Server: [render Header][render Data][render Footer] -> send everything
// Time: 500ms + 2000ms + 100ms = 2600ms before they see anything

// Streaming SSR - fragments sent immediately
// Server: [Header ready] -> send! [Data ready] -> send! [Footer] -> send!
// Time: 500ms to first fragment, rest arrives in background

renderToPipeableStream - Streaming API

React 18 introduced renderToPipeableStream, the streaming successor of renderToString, which had to render the whole page before sending the first byte:

import { renderToPipeableStream } from 'react-dom/server';

// Node.js server with Streaming SSR
app.get('/', (req, res) => {
  const { pipe } = renderToPipeableStream(
    <App />,
    {
      bootstrapScripts: ['/main.js'],
      onShellReady() {
        // Shell is ready - send immediately
        res.setHeader('Content-Type', 'text/html');
        pipe(res);
      },
      onShellError(error) {
        // Error in critical part - send fallback
        res.statusCode = 500;
        res.send('<h1>Server Error</h1>');
      },
      onAllReady() {
        // Everything ready (useful for crawlers/SEO)
      },
      onError(error) {
        console.error('Streaming error:', error);
      }
    }
  );
});

onShellReady is called when the main "shell" of the page is ready - everything outside <Suspense> boundaries. The user sees the page skeleton immediately.

renderToReadableStream - Edge Runtime API

For Edge Runtime (Cloudflare Workers, Vercel Edge, Deno Deploy) we use renderToReadableStream, which returns a Web Streams API:

import { renderToReadableStream } from 'react-dom/server';

// Edge Runtime handler
export default async function handler(request) {
  const stream = await renderToReadableStream(
    <App />,
    {
      bootstrapScripts: ['/main.js'],
      onError(error) {
        console.error('Edge streaming error:', error);
      }
    }
  );

  return new Response(stream, {
    headers: { 'Content-Type': 'text/html' },
  });
}

Difference between APIs:

  • renderToPipeableStream - Node.js Streams (Node.js runtime)
  • renderToReadableStream - Web Streams API (Edge Runtime, Deno, browsers)

Since React 19.2 renderToReadableStream also works in Node.js, but the React team still recommends renderToPipeableStream there: Node.js streams are faster in Node, and Web Streams do not support compression by default.

Suspense as Streaming Boundaries

<Suspense> defines streaming boundaries - the server sends a fallback and later replaces it with the ready HTML:

function SpaceStationDashboard() {
  return (
    <div>
      {/* Rendered immediately - part of "shell" */}
      <Header title="Space Station Alpha" />
      <Navigation />

      {/* Each section streams independently */}
      <Suspense fallback={<Skeleton type="missions" />}>
        <MissionList />  {/* Data loads in 800ms */}
      </Suspense>

      <Suspense fallback={<Skeleton type="crew" />}>
        <CrewStatus />   {/* Data loads in 1500ms */}
      </Suspense>

      <Suspense fallback={<Skeleton type="telemetry" />}>
        <TelemetryData />  {/* Data loads in 2200ms */}
      </Suspense>
    </div>
  );
}

// Streaming flow:
// 1. [0ms]    Server sends: Header + Navigation + 3x Skeleton
// 2. [800ms]  Server streams: MissionList (replaces Skeleton)
// 3. [1500ms] Server streams: CrewStatus (replaces Skeleton)
// 4. [2200ms] Server streams: TelemetryData (replaces Skeleton)

Errors and Data Inside Suspense Boundaries

Suspense only handles waiting for data. If fetching fails, the component throws an error, and the nearest Error Boundary catches it. That is why a slow section gets wrapped in two layers: an Error Boundary outside and Suspense inside. In such a component you can conveniently fetch data with the useSuspenseQuery hook from TanStack Query, which suspends the component until the data arrives:

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import { useSuspenseQuery } from '@tanstack/react-query';

function MissionList() {
  // data is always defined: Suspense handles loading and the Error Boundary handles errors
  const { data } = useSuspenseQuery({ queryKey: ['missions'], queryFn: fetchMissions });

  return (
    <ul>
      {data.map(mission => (
        <li key={mission.id}>{mission.name}</li>
      ))}
    </ul>
  );
}

function MissionsSection() {
  return (
    <ErrorBoundary fallback={<MissionsError />}>
      <Suspense fallback={<Skeleton type="missions" />}>
        <MissionList />
      </Suspense>
    </ErrorBoundary>
  );
}

While loading you see the skeleton from Suspense, and when the query fails, the ErrorBoundary from the react-error-boundary package shows MissionsError in place of the whole section. On the server it works in a similar way: if a component inside a Suspense boundary throws an error during streaming, React does not abort the response, it sends that boundary's fallback and retries rendering in the browser. Only when that fails too does the error reach the nearest Error Boundary. An error in the shell itself, outside all boundaries, triggers onShellError.

Edge Runtime - Computations Closer to the User

Edge Runtime is a lightweight execution environment running on the "edge" of the network, on CDN servers spread around the world, close to the user. Instead of full Node.js it runs code in isolates of the V8 engine (the same engine that runs JavaScript in Chrome) and gives it Web APIs: fetch, Request, Response and Web Streams. An isolate starts roughly a hundred times faster than a Node.js process, which is why a cold start here takes just a few milliseconds. This is what React streaming looks like in Cloudflare Workers:

// worker.jsx - Cloudflare Workers (V8 isolates, Web APIs instead of Node.js)
import { renderToReadableStream } from 'react-dom/server';
import App from './App';

export default {
  async fetch(request) {
    // Cloudflare attaches the user's location data to the request
    const city = request.cf?.city ?? 'unknown city';

    const stream = await renderToReadableStream(<App city={city} />, {
      bootstrapScripts: ['/main.js'],
    });

    return new Response(stream, {
      headers: { 'Content-Type': 'text/html; charset=utf-8' },
    });
  },
};

The worker has no access to the file system or to Node.js modules, but it responds from the server closest to the user. The location comes from the platform here, through request.cf, not from React. In Next.js the request.geo object was removed in version 15, and on Vercel you read the city with the geolocation() function from the @vercel/functions package.

Differences: Node.js vs Edge Runtime

The table shows what you pay for an instant start at the edge of the network. Cold start times are indicative and depend on the platform:

FeatureNode.js RuntimeEdge Runtime
LocationOne or several regionsCDN servers around the world
Cold start200-500ms (cold serverless function)1-5ms (V8 isolate)
Code sizeLarge limit (e.g. 250 MB on Vercel)1-4 MB after compression (Vercel, depending on the plan)
APIFull Node.js APIWeb APIs, no file system or Node.js modules
StreamingrenderToPipeableStreamrenderToReadableStream
DatabasesAnyDrivers that work over HTTP (e.g. Turso, Neon)

Edge Runtime in Next.js 16

The fast-start advantage is shrinking, because platforms also shorten Node.js cold starts. Fluid compute on Vercel caches compiled bytecode and pre-warms functions in production, which is why Vercel now recommends moving functions from Edge to Node.js. Next.js went the same way: in version 16 the middleware.ts file was renamed to proxy.ts and always runs on Node.js, and in version 16.3 the runtime = 'edge' export in page and route handler files became deprecated. Next.js warns about it and advises removing it, because the default Node.js runtime needs no configuration, and Vercel runs such routes on Node.js:

// proxy.js (Next.js 16, formerly middleware.js) - always the Node.js runtime
import { NextResponse } from 'next/server';

export function proxy(request) {
  const isDashboard = request.nextUrl.pathname.startsWith('/dashboard');

  // Without a session, redirect to login before the page starts rendering
  if (isDashboard && !request.cookies.has('session')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

Proxy runs before every route is rendered, so in a real project narrow it down with the matcher option in the config object. Edge Runtime is not disappearing from the ecosystem, though: it remains the natural environment of platforms built on isolates, such as Cloudflare Workers or Deno Deploy, and renderToReadableStream works there unchanged.

Progressive Hydration

Streaming SSR naturally supports progressive hydration - React hydrates components as they appear:

// Progressive hydration flow:
// 1. Server streams HTML -> browser displays
// 2. JavaScript loads
// 3. React hydrates components already in DOM
// 4. New HTML fragments arrive from stream
// 5. React hydrates them immediately upon receipt

// Selective hydration - React prioritizes
// components the user interacts with:
function App() {
  return (
    <div>
      {/* User clicked here - React hydrates this FIRST */}
      <Suspense fallback={<Skeleton />}>
        <InteractivePanel />
      </Suspense>

      {/* This waits in queue */}
      <Suspense fallback={<Skeleton />}>
        <HeavyDataTable />
      </Suspense>
    </div>
  );
}

Summary

Streaming SSR and Edge Runtime are powerful tools for accelerating application delivery:

  1. Streaming SSR - sends HTML in fragments, user sees the page immediately
  2. renderToPipeableStream - Node.js API for streaming
  3. renderToReadableStream - Web Streams API (Edge Runtime, Cloudflare Workers, Deno)
  4. Suspense boundaries - define streaming boundaries, and an Error Boundary above them catches errors
  5. Edge Runtime - code close to the user and a fast cold start, but in Next.js 16 the default and recommended environment is Node.js
  6. Progressive Hydration - React hydrates components as they appear

Streaming SSR changes application delivery like modular systems on a space station - each module launches independently, the user does not wait for the whole thing. In the example below the sections arrive in the order their data becomes ready, and after you tick the relay failure and send a new request, you will see the Error Boundary catch one section's error while the rest of the page keeps working.

Code for this lesson: App.jsx
import { Component, Suspense, use, useCallback, useEffect, useState } from 'react';

// === STREAMING SSR - a simulation in the browser ===
// The shell (header and layout) appears immediately, and each Suspense boundary
// shows a skeleton until its data arrives. Sections arrive in the order their
// data becomes ready, not in their order on the page.

const DATA = {
  missions: [
    { id: 1, name: 'Mars Expedition', status: 'active', eta: '47 days' },
    { id: 2, name: 'Europa Probe', status: 'planned', eta: '182 days' },
    { id: 3, name: 'Lunar Base', status: 'completed', eta: '-' },
  ],
  crew: [
    { id: 1, name: 'Commander Nova', role: 'Mission lead', ready: true },
    { id: 2, name: 'Astro', role: 'Navigator', ready: true },
    { id: 3, name: 'Ra', role: 'Guide', ready: false },
  ],
  telemetry: [
    { label: 'Oxygen', value: 96 },
    { label: 'Fuel', value: 78 },
    { label: 'Hull', value: 99 },
    { label: 'Comms', value: 87 },
  ],
  earth: 'Earth Control confirms the course. Good luck, crew!',
};

const DELAYS = { missions: 600, earth: 900, crew: 1200, telemetry: 2000 };

// One promise per section in a given request. The same promise on the next
// render lets the use() hook read the ready data.
const requests = new Map();

// When the current request started (for the timeline)
let requestStart = performance.now();

function loadSection(section, requestKey, fail = false) {
  const key = section + ':' + requestKey;
  if (!requests.has(key)) {
    requests.set(key, new Promise((resolve, reject) => {
      setTimeout(() => {
        if (fail) reject(new Error('No signal from the orbital relay'));
        else resolve(DATA[section]);
      }, DELAYS[section]);
    }));
  }
  return requests.get(key);
}

// Error Boundary: catches an error thrown while a section renders
class RelayBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { error: null };
  }

  static getDerivedStateFromError(error) {
    return { error };
  }

  componentDidCatch(error) {
    this.props.onError(error.message);
  }

  render() {
    if (this.state.error) {
      return (
        <div style={styles.errorBox}>
          <strong>Connection lost</strong>
          <p style={{ margin: '4px 0 8px' }}>{this.state.error.message}</p>
          <button
            style={styles.smallButton}
            onClick={() => {
              this.props.onRetry();
              this.setState({ error: null });
            }}
          >
            Try again
          </button>
        </div>
      );
    }
    return this.props.children;
  }
}

function Skeleton({ label }) {
  return (
    <div style={styles.skeleton}>
      <div style={styles.shimmer} />
      <p style={styles.skeletonLabel}>Waiting for section: {label}...</p>
    </div>
  );
}

function MissionPanel({ requestId, onReady }) {
  const missions = use(loadSection('missions', requestId));
  useEffect(() => {
    onReady('Missions', '#00ff88');
  }, [onReady]);

  return (
    <div style={styles.panel}>
      <h3 style={styles.panelTitle}>Missions (600 ms)</h3>
      {missions.map(m => (
        <div key={m.id} style={styles.item}>
          <span style={styles.badge}>{m.status}</span>
          <strong>{m.name}</strong>
          <span style={styles.muted}>ETA: {m.eta}</span>
        </div>
      ))}
    </div>
  );
}

function CrewPanel({ requestId, onReady }) {
  const crew = use(loadSection('crew', requestId));
  useEffect(() => {
    onReady('Crew', '#ffaa00');
  }, [onReady]);

  return (
    <div style={styles.panel}>
      <h3 style={styles.panelTitle}>Crew (1200 ms)</h3>
      {crew.map(c => (
        <div key={c.id} style={styles.item}>
          <span style={{ ...styles.dot, background: c.ready ? '#00ff88' : '#ff6b6b' }} />
          <strong>{c.name}</strong>
          <span style={styles.muted}>{c.role}</span>
        </div>
      ))}
    </div>
  );
}

function TelemetryPanel({ requestId, onReady }) {
  const telemetry = use(loadSection('telemetry', requestId));
  useEffect(() => {
    onReady('Telemetry', '#ff6b6b');
  }, [onReady]);

  return (
    <div style={styles.panel}>
      <h3 style={styles.panelTitle}>Telemetry (2000 ms)</h3>
      <div style={styles.telGrid}>
        {telemetry.map(t => (
          <div key={t.label} style={styles.telItem}>
            <span style={styles.telLabel}>{t.label}</span>
            <div style={styles.bar}>
              <div style={{ ...styles.barFill, width: t.value + '%' }} />
            </div>
            <span>{t.value}%</span>
          </div>
        ))}
      </div>
    </div>
  );
}

function EarthPanel({ requestKey, fail, label, onReady }) {
  const message = use(loadSection('earth', requestKey, fail));
  useEffect(() => {
    onReady(label, '#00d4ff');
  }, [onReady, label]);

  return (
    <div style={styles.panel}>
      <h3 style={styles.panelTitle}>Contact with Earth (900 ms)</h3>
      <p style={{ margin: 0, fontSize: '12px' }}>{message}</p>
    </div>
  );
}

export default function App() {
  const [request, setRequest] = useState({ id: 1, fail: false });
  const [failNext, setFailNext] = useState(false);
  const [attempt, setAttempt] = useState(0);
  const [events, setEvents] = useState([{ label: 'Shell (header and layout)', ms: 0, color: '#8892b0' }]);
  // A section reports itself after rendering, so the timeline shows the real order
  const report = useCallback((label, color) => {
    const ms = Math.round(performance.now() - requestStart);
    setEvents(prev => (prev.some(e => e.label === label) ? prev : [...prev, { label, ms, color }]));
  }, []);

  const reportError = useCallback(message => {
    report('Connection error: ' + message, '#ff6b6b');
  }, [report]);

  const startRequest = () => {
    requestStart = performance.now();
    setAttempt(0);
    setEvents([{ label: 'Shell (header and layout)', ms: 0, color: '#8892b0' }]);
    setRequest(r => ({ id: r.id + 1, fail: failNext }));
  };

  const earthFails = request.fail && attempt === 0;
  const earthLabel = attempt === 0 ? 'Contact with Earth' : 'Contact with Earth (retry)';

  return (
    <div style={styles.container}>
      <header style={styles.header}>
        <h1 style={styles.title}>Streaming SSR - simulation</h1>
        <p style={styles.subtitle}>
          The shell appears immediately, and each Suspense boundary streams in its section when its data is ready
        </p>
        <div style={styles.toolbar}>
          <button style={styles.button} onClick={startRequest}>New request</button>
          <label style={styles.checkbox}>
            <input type="checkbox" checked={failNext} onChange={e => setFailNext(e.target.checked)} />
            Relay failure in the next request
          </label>
        </div>
      </header>

      <section style={styles.shell}>
        <h2 style={{ color: '#00d4ff', margin: 0, fontSize: '16px' }}>Station Alpha - Dashboard (request #{request.id})</h2>
        <p style={{ color: '#8892b0', margin: '2px 0 0', fontSize: '11px' }}>Shell: sent immediately (0 ms)</p>
      </section>

      <div style={styles.mainGrid}>
        <div key={request.id} style={styles.grid}>
          <Suspense fallback={<Skeleton label="Missions" />}>
            <MissionPanel requestId={request.id} onReady={report} />
          </Suspense>

          <RelayBoundary onError={reportError} onRetry={() => setAttempt(a => a + 1)}>
            <Suspense fallback={<Skeleton label="Contact with Earth" />}>
              <EarthPanel
                requestKey={request.id + '-' + attempt}
                fail={earthFails}
                label={earthLabel}
                onReady={report}
              />
            </Suspense>
          </RelayBoundary>

          <Suspense fallback={<Skeleton label="Crew" />}>
            <CrewPanel requestId={request.id} onReady={report} />
          </Suspense>

          <Suspense fallback={<Skeleton label="Telemetry" />}>
            <TelemetryPanel requestId={request.id} onReady={report} />
          </Suspense>
        </div>

        <aside style={styles.timeline}>
          <h3 style={styles.panelTitle}>Streaming order</h3>
          {events.map(e => (
            <div key={e.label} style={styles.timelineItem}>
              <span style={{ ...styles.dot, background: e.color }} />
              <span style={styles.time}>{e.ms} ms</span>
              <span>{e.label}</span>
            </div>
          ))}
        </aside>
      </div>
    </div>
  );
}

const styles = {
  container: { fontFamily: 'system-ui, sans-serif', background: '#0a0e17', color: '#e0e1dd', minHeight: '100vh', padding: '14px' },
  header: { textAlign: 'center', marginBottom: '12px' },
  title: { fontSize: '20px', color: '#00d4ff', margin: '0 0 4px' },
  subtitle: { fontSize: '12px', color: '#8892b0', margin: '0 0 10px' },
  toolbar: { display: 'flex', gap: '12px', justifyContent: 'center', alignItems: 'center', flexWrap: 'wrap' },
  button: { padding: '6px 14px', background: '#00d4ff', color: '#0a0e17', border: 'none', borderRadius: '6px', fontWeight: 'bold', cursor: 'pointer' },
  smallButton: { padding: '4px 10px', background: 'transparent', color: '#ff6b6b', border: '1px solid #ff6b6b', borderRadius: '6px', cursor: 'pointer', fontSize: '11px' },
  checkbox: { display: 'flex', alignItems: 'center', gap: '6px', fontSize: '12px', color: '#8892b0' },
  shell: { background: 'rgba(0,212,255,0.08)', border: '1px solid rgba(0,212,255,0.2)', borderRadius: '8px', padding: '10px 12px', marginBottom: '12px' },
  mainGrid: { display: 'grid', gridTemplateColumns: 'minmax(0, 1fr) 210px', gap: '12px' },
  grid: { display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: '10px', alignContent: 'start' },
  panel: { background: 'rgba(0,212,255,0.05)', borderRadius: '8px', padding: '12px', border: '1px solid rgba(0,212,255,0.15)' },
  panelTitle: { fontSize: '13px', color: '#00d4ff', margin: '0 0 8px' },
  item: { display: 'flex', alignItems: 'center', gap: '6px', padding: '5px 8px', background: 'rgba(0,0,0,0.3)', borderRadius: '4px', marginBottom: '4px', fontSize: '11px' },
  badge: { padding: '1px 6px', borderRadius: '6px', fontSize: '9px', background: 'rgba(0,255,136,0.15)', color: '#00ff88' },
  muted: { marginLeft: 'auto', color: '#8892b0', fontSize: '10px' },
  dot: { width: '8px', height: '8px', borderRadius: '50%', flexShrink: 0, display: 'inline-block' },
  skeleton: { minHeight: '110px', background: 'rgba(0,212,255,0.03)', border: '1px dashed rgba(0,212,255,0.2)', borderRadius: '8px', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center' },
  shimmer: { width: '50%', height: '8px', background: 'rgba(0,212,255,0.12)', borderRadius: '4px', marginBottom: '6px' },
  skeletonLabel: { color: '#8892b0', fontSize: '11px', margin: 0 },
  errorBox: { minHeight: '110px', background: 'rgba(255,107,107,0.08)', border: '1px solid rgba(255,107,107,0.4)', borderRadius: '8px', padding: '12px', fontSize: '12px', color: '#ffb3b3' },
  telGrid: { display: 'grid', gap: '6px' },
  telItem: { display: 'flex', alignItems: 'center', gap: '6px', fontSize: '11px' },
  telLabel: { color: '#8892b0', width: '60px' },
  bar: { flex: 1, height: '8px', background: 'rgba(255,255,255,0.08)', borderRadius: '4px', overflow: 'hidden' },
  barFill: { height: '100%', background: 'linear-gradient(90deg, #00d4ff, #00ff88)' },
  timeline: { background: 'rgba(0,212,255,0.05)', borderRadius: '8px', padding: '12px', border: '1px solid rgba(0,212,255,0.15)', alignSelf: 'start' },
  timelineItem: { display: 'flex', alignItems: 'center', gap: '6px', marginBottom: '8px', fontSize: '11px' },
  time: { color: '#8892b0', width: '48px', textAlign: 'right', flexShrink: 0 },
};

Docs entries used in this lesson

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What is the main difference between renderToPipeableStream and renderToReadableStream?

  2. 2. Which feature is the MAIN advantage of Edge Runtime compared to traditional Node.js?

Hands-on tasks in the game

  • Vertical ordering

    Order the stages of Streaming SSR from first to last:

  • Horizontal ordering

    Arrange wrapping a component in ErrorBoundary + Suspense from left to right:

  • Click in order

    Arrange the useSuspenseQuery syntax with TanStack React Query:

  1. QuestionrenderToPipeableStream vs renderToReadableStream
  2. Put in orderStreaming SSR - Event Sequence
  3. QuestionEdge Runtime - Characteristics
  4. Put in orderErrorBoundary with Suspense Syntax
  5. Click in orderuseSuspenseQuery Syntax with React Query

Useful articles