| name | bun-react-ssr |
| description | Use when building server-rendered React with Bun, including streaming SSR, hydration, renderToString, or custom SSR without a framework. |
| metadata | {"version":"1.0.0"} |
| license | MIT |
Bun React SSR
Build custom server-rendered React applications with Bun.
Quick Start
mkdir my-ssr-app && cd my-ssr-app
bun init
bun add react react-dom
bun add -D @types/react @types/react-dom
Basic SSR Setup
Server Entry
import { renderToString } from "react-dom/server";
import App from "./App";
Bun.serve({
port: 3000,
async fetch(req) {
const url = new URL(req.url);
if (url.pathname.startsWith("/static/")) {
const file = Bun.file(`./public${url.pathname}`);
if (await file.exists()) {
return new Response(file);
}
}
const html = renderToString(<App url={url.pathname} />);
return new Response(
`<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>React SSR</title>
</head>
<body>
<div id="root">${html}</div>
<script src="/static/client.js"></script>
</body>
</html>`,
{
headers: { "Content-Type": "text/html" },
}
);
},
});
console.log("Server running on http://localhost:3000");
Client Entry
import { hydrateRoot } from "react-dom/client";
import App from "./App";
hydrateRoot(
document.getElementById("root")!,
<App url={window.location.pathname} />
);
React App
interface AppProps {
url: string;
}
export default function App({ url }: AppProps) {
return (
<div>
<h1>React SSR with Bun</h1>
<p>Current path: {url}</p>
<button onClick={() => alert("Hydrated!")}>Click me</button>
</div>
);
}
Build Client Bundle
await Bun.build({
entrypoints: ["./src/client.tsx"],
outdir: "./public/static",
target: "browser",
minify: true,
splitting: true,
});
bun run build.ts
bun run src/server.tsx
Streaming SSR
import { renderToReadableStream } from "react-dom/server";
import App from "./App";
Bun.serve({
port: 3000,
async fetch(req) {
const url = new URL(req.url);
const stream = await renderToReadableStream(
<App url={url.pathname} />,
{
bootstrapScripts: ["/static/client.js"],
onError(error) {
console.error(error);
},
}
);
await stream.allReady;
return new Response(stream, {
headers: { "Content-Type": "text/html" },
});
},
});
With Suspense
import { Suspense } from "react";
function SlowComponent() {
return <div>Loaded!</div>;
}
export default function App({ url }: { url: string }) {
return (
<html>
<head>
<title>Streaming SSR</title>
</head>
<body>
<div id="root">
<h1>Fast Shell</h1>
<Suspense fallback={<div>Loading...</div>}>
<SlowComponent />
</Suspense>
</div>
</body>
</html>
);
}
Data Fetching
Server-Side Data
import { renderToString } from "react-dom/server";
import { Database } from "bun:sqlite";
import App from "./App";
const db = new Database("data.sqlite");
Bun.serve({
async fetch(req) {
const url = new URL(req.url);
const users = db.query("SELECT * FROM users").all();
const html = renderToString(
<App url={url.pathname} initialData={{ users }} />
);
return new Response(
`<!DOCTYPE html>
<html>
<head><title>SSR</title></head>
<body>
<div id="root">${html}</div>
<script>
window.__INITIAL_DATA__ = ${JSON.stringify({ users })};
</script>
<script src="/static/client.js"></script>
</body>
</html>`,
{ headers: { "Content-Type": } }
);
},
});
Client Hydration
import { hydrateRoot } from "react-dom/client";
import App from "./App";
const initialData = (window as any).__INITIAL_DATA__;
hydrateRoot(
document.getElementById("root")!,
<App url={window.location.pathname} initialData={initialData} />
);
Routing
Simple Router
import { useState, useEffect } from "react";
interface Route {
path: string;
component: React.ComponentType;
}
interface RouterProps {
routes: Route[];
initialPath: string;
}
export function Router({ routes, initialPath }: RouterProps) {
const [path, setPath] = useState(initialPath);
useEffect(() => {
const handlePopState = () => setPath(window.location.pathname);
window.addEventListener("popstate", handlePopState);
return () => window.removeEventListener("popstate", handlePopState);
}, []);
const route = routes.find((r) => r.path === path);
const Component = route?.component || NotFound;
;
}
() {
= () => {
e.();
..({}, , href);
.( ());
};
;
}
() {
;
}
CSS Handling
Inline Styles
const html = renderToString(<App />);
return new Response(
`<!DOCTYPE html>
<html>
<head>
<style>${await Bun.file("./src/styles.css").text()}</style>
</head>
<body>
<div id="root">${html}</div>
</body>
</html>`,
{ headers: { "Content-Type": "text/html" } }
);
External Stylesheet
await Bun.build({
entrypoints: ["./src/styles.css"],
outdir: "./public/static",
});
`<link rel="stylesheet" href="/static/styles.css">`
Development Setup
Hot Reload Development
import { watch } from "fs";
const srcDir = "./src";
let serverProcess: Subprocess | null = null;
async function startServer() {
serverProcess?.kill();
serverProcess = Bun.spawn(["bun", "run", "src/server.tsx"], {
stdout: "inherit",
stderr: "inherit",
});
}
watch(srcDir, { recursive: true }, async (event, filename) => {
console.log(`Change detected: ${filename}`);
await startServer();
});
await startServer();
console.log("Dev server watching...");
Production Build
await Bun.build({
entrypoints: ["./src/client.tsx"],
outdir: "./dist/public/static",
target: "browser",
minify: true,
splitting: true,
sourcemap: "external",
});
await Bun.build({
entrypoints: ["./src/server.tsx"],
outdir: "./dist",
target: "bun",
minify: true,
});
console.log("Build complete!");
Common Errors
| Error | Cause | Fix |
|---|
Hydration mismatch | Server/client HTML differs | Check initial state |
document is not defined | SSR accessing DOM | Guard with typeof window |
Cannot use hooks | Hooks outside component | Check component structure |
Flash of unstyled content | CSS not loaded | Inline critical CSS |
Performance Tips
- Use streaming SSR for faster TTFB
- Inline critical CSS above the fold
- Code split client bundle
- Cache rendered HTML for static pages
- Use Suspense for progressive loading
When to Load References
Load references/streaming-patterns.md when:
- Complex Suspense boundaries
- Selective hydration
- Progressive enhancement
Load references/caching.md when:
- HTML caching strategies
- CDN integration
- Edge rendering
