Use when building server-rendered React with Bun, including streaming SSR, hydration, renderToString, or custom SSR without a framework.
Build custom server-rendered React apps with Bun using renderToString or streaming SSR. Use when setting up SSR from scratch without a framework, handling hydration, or implementing data fetching patterns.
/plugin marketplace add secondsky/claude-skills/plugin install bun@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Build custom server-rendered React applications with Bun.
# Initialize project
mkdir my-ssr-app && cd my-ssr-app
bun init
# Install dependencies
bun add react react-dom
bun add -D @types/react @types/react-dom
// src/server.tsx
import { renderToString } from "react-dom/server";
import App from "./App";
Bun.serve({
port: 3000,
async fetch(req) {
const url = new URL(req.url);
// Serve static files
if (url.pathname.startsWith("/static/")) {
const file = Bun.file(`./public${url.pathname}`);
if (await file.exists()) {
return new Response(file);
}
}
// Render React app
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");
// src/client.tsx
import { hydrateRoot } from "react-dom/client";
import App from "./App";
hydrateRoot(
document.getElementById("root")!,
<App url={window.location.pathname} />
);
// src/App.tsx
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.ts
await Bun.build({
entrypoints: ["./src/client.tsx"],
outdir: "./public/static",
target: "browser",
minify: true,
splitting: true,
});
# Build client
bun run build.ts
# Start server
bun run src/server.tsx
// src/server-streaming.tsx
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);
},
}
);
// Wait for shell to be ready (Suspense boundaries)
await stream.allReady;
return new Response(stream, {
headers: { "Content-Type": "text/html" },
});
},
});
// src/App.tsx
import { Suspense } from "react";
function SlowComponent() {
// This would be a data fetching component
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>
);
}
// src/server.tsx
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);
// Fetch data server-side
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": "text/html" } }
);
},
});
// src/client.tsx
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} />
);
// src/Router.tsx
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;
return <Component />;
}
export function Link({ href, children }: { href: string; children: React.ReactNode }) {
const handleClick = (e: React.MouseEvent) => {
e.preventDefault();
window.history.pushState({}, "", href);
window.dispatchEvent(new PopStateEvent("popstate"));
};
return <a href={href} onClick={handleClick}>{children}</a>;
}
function NotFound() {
return <h1>404 - Not Found</h1>;
}
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" } }
);
// Build CSS
await Bun.build({
entrypoints: ["./src/styles.css"],
outdir: "./public/static",
});
// Link in HTML
`<link rel="stylesheet" href="/static/styles.css">`
// dev.ts
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 for changes
watch(srcDir, { recursive: true }, async (event, filename) => {
console.log(`Change detected: ${filename}`);
await startServer();
});
await startServer();
console.log("Dev server watching...");
// build-prod.ts
// Build client
await Bun.build({
entrypoints: ["./src/client.tsx"],
outdir: "./dist/public/static",
target: "browser",
minify: true,
splitting: true,
sourcemap: "external",
});
// Build server
await Bun.build({
entrypoints: ["./src/server.tsx"],
outdir: "./dist",
target: "bun",
minify: true,
});
console.log("Build complete!");
| 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 |
Load references/streaming-patterns.md when:
Load references/caching.md when:
Use when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.