Server-Side Rendering (SSR)

Server-Side Rendering (SSR) lets you render Preact components to HTML on the server. This improves initial page load performance, SEO, and provides a better experience for users on slow connections.

Why Use SSR?

Better Performance

Users see content faster since HTML is sent immediately instead of waiting for JavaScript to load and execute.

Improved SEO

Search engines can index your content immediately without executing JavaScript.

Social Media

Social media crawlers can read your content for previews and cards.

Accessibility

Content is available even if JavaScript fails to load or is disabled.

Installation

SSR requires the preact-render-to-string package:

npm install preact-render-to-string

This package provides functions to render Preact components to HTML strings.

Basic Usage

renderToString
renderToStaticMarkup

The most common SSR function. Renders a component tree to an HTML string:

import { renderToString } from 'preact-render-to-string';
import { App } from './App';

// Render to HTML string
const html = renderToString(<App />);

console.log(html);
// Output: <div class="app">...</div>

This is a synchronous function that returns a complete HTML string.

Same as renderToString but omits Preact-specific attributes:

import { renderToStaticMarkup } from 'preact-render-to-string';
import { App } from './App';

// Render to static HTML (no hydration markers)
const html = renderToStaticMarkup(<App />);

Use this when you won’t hydrate the HTML on the client (e.g., for emails).

Integration with Servers

import express from 'express';
import { renderToString } from 'preact-render-to-string';
import { App } from './App';

const app = express();

app.get('*', (req, res) => {
  const html = renderToString(<App url={req.url} />);
  
  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <title>My App</title>
        <link rel="stylesheet" href="/styles.css">
      </head>
      <body>
        <div id="app">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);

import { createServer } from 'http';
import { renderToString } from 'preact-render-to-string';
import { App } from './App';

const server = createServer((req, res) => {
  const html = renderToString(<App url={req.url} />);
  
  res.writeHead(200, { 'Content-Type': 'text/html' });
  res.end(`
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <title>My App</title>
      </head>
      <body>
        <div id="app">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
});

server.listen(3000);

import Fastify from 'fastify';
import { renderToString } from 'preact-render-to-string';
import { App } from './App';

const fastify = Fastify();

fastify.get('*', (request, reply) => {
  const html = renderToString(<App url={request.url} />);
  
  reply.type('text/html').send(`
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <title>My App</title>
      </head>
      <body>
        <div id="app">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
});

fastify.listen({ port: 3000 });

Hydration

After sending server-rendered HTML, you need to “hydrate” it on the client. Hydration attaches event listeners and makes the app interactive.

The component tree must be identical on server and client, or hydration will fail and Preact will re-render from scratch.

Streaming SSR

For large applications, streaming can improve Time To First Byte (TTFB):

renderToReadableStream (Web)
renderToPipeableStream (Node)

Returns a ReadableStream for use in modern web environments:

import { renderToReadableStream } from 'preact-render-to-string/stream';
import { App } from './App';

// Modern web server (e.g., Cloudflare Workers)
export default {
  async fetch(request) {
    const stream = await renderToReadableStream(<App />);
    
    return new Response(stream, {
      headers: { 'Content-Type': 'text/html' }
    });
  }
};

Returns a pipeable stream for Node.js:

import { renderToPipeableStream } from 'preact-render-to-string/stream-node';
import { App } from './App';

app.get('*', (req, res) => {
  res.setHeader('Content-Type', 'text/html');
  
  const stream = renderToPipeableStream(<App />);
  
  stream.pipe(res);
});

Compat Layer

When using preact/compat, SSR functions are re-exported for React compatibility:

// From compat/server.d.ts
import { 
  renderToString,
  renderToStaticMarkup,
  renderToPipeableStream,
  renderToReadableStream 
} from 'preact-render-to-string';

Reference: compat/server.d.ts You can import from preact/compat/server just like react-dom/server:

import { renderToString } from 'preact/compat/server';

Data Fetching

For SSR with data fetching, you’ll need to fetch data on the server before rendering:

import express from 'express';
import { renderToString } from 'preact-render-to-string';
import { App } from './App';

const app = express();

app.get('/user/:id', async (req, res) => {
  // Fetch data on server
  const user = await fetch(`https://api.example.com/users/${req.params.id}`)
    .then(r => r.json());
  
  // Pass data to component
  const html = renderToString(<App user={user} />);
  
  res.send(`
    <!DOCTYPE html>
    <html>
      <body>
        <div id="app">${html}</div>
        <script>
          window.__INITIAL_DATA__ = ${JSON.stringify({ user })};
        </script>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
});

import { hydrate } from 'preact';
import { App } from './App';

// Get initial data from server
const initialData = window.__INITIAL_DATA__;

// Hydrate with same data
hydrate(
  <App user={initialData.user} />,
  document.getElementById('app')
);

// Clean up
delete window.__INITIAL_DATA__;

import { createContext } from 'preact';
import { useContext } from 'preact/hooks';

const DataContext = createContext(null);

// Server
const data = await fetchData();
const html = renderToString(
  <DataContext.Provider value={data}>
    <App />
  </DataContext.Provider>
);

// Component
function UserProfile() {
  const data = useContext(DataContext);
  return <div>{data.user.name}</div>;
}

// Client
const initialData = window.__INITIAL_DATA__;
hydrate(
  <DataContext.Provider value={initialData}>
    <App />
  </DataContext.Provider>,
  document.getElementById('app')
);

Best Practices

Common Patterns

import { renderToString } from 'preact-render-to-string';
import { Router } from 'preact-router';
import { App } from './App';

app.get('*', (req, res) => {
  const html = renderToString(
    <Router url={req.url}>
      <App />
    </Router>
  );
  
  res.send(html);
});

import { writeFileSync } from 'fs';
import { renderToString } from 'preact-render-to-string';
import { App } from './App';

const routes = ['/', '/about', '/contact'];

routes.forEach(route => {
  const html = renderToString(<App url={route} />);
  
  const page = `
    <!DOCTYPE html>
    <html>
      <body>
        <div id="app">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `;
  
  writeFileSync(`dist${route}/index.html`, page);
});

import { renderToString } from 'preact-render-to-string';

// Helper to wait for async data
async function renderWithData(component) {
  const data = await fetchAllData();
  return renderToString(component(data));
}

app.get('/user/:id', async (req, res) => {
  const html = await renderWithData(
    (data) => <App user={data.user} />
  );
  
  res.send(html);
});

Getting Started

Core Concepts

Guides

React Compatibility

Advanced

Server-Side Rendering (SSR)

Why Use SSR?

Better Performance

Improved SEO

Social Media

Accessibility

Installation

Basic Usage

Integration with Servers

Hydration

Streaming SSR

Compat Layer

Data Fetching

Best Practices

Common Patterns

Next Steps

TypeScript

Hooks

​Why Use SSR?

Better Performance

Improved SEO

Social Media

Accessibility

​Installation

​Basic Usage

​Integration with Servers

​Hydration

​Streaming SSR

​Compat Layer

​Data Fetching

​Best Practices

​Common Patterns

​Next Steps

TypeScript

Hooks

Why Use SSR?

Installation

Basic Usage

Integration with Servers

Hydration

Streaming SSR

Compat Layer

Data Fetching

Best Practices

Common Patterns

Next Steps