docs: vite + ssr

RihanArfan · RihanArfan · commit d25b45e01397 · 2026-02-27T14:05:07.000Z
diff --git a/docs/1.docs/4.renderer.md b/docs/1.docs/4.renderer.md
@@ -174,6 +174,111 @@ If you define a catch-all route (`[...].ts`) in your routes, Nitro will warn you
 
 :read-more{to="/docs/lifecycle" title="Lifecycle"}
 
+## Server-Side Rendering (SSR)
+
+Nitro supports full server-side rendering through Vite's [environment API](https://vite.dev/guide/api-environment). With SSR, Nitro renders your application to HTML on the server, sends it to the browser, and the client hydrates the page to make it interactive.
+
+This requires two entry files:
+
+- **Server entry** (`entry-server`) — renders the app to HTML on the server.
+- **Client entry** (`entry-client`) — hydrates the server-rendered HTML in the browser.
+
+### Auto-detected entry points
+
+Nitro automatically detects `entry-server` and `entry-client` files in your project's `app/`, `src/`, or root directory. No Vite configuration is needed when you follow this convention.
+
+```
+app/
+  entry-server.ts    ← auto-detected as SSR entry
+  entry-client.ts    ← auto-detected as client entry
+routes/
+  api/hello.ts
+```
+
+::tip
+When entry files are detected, Nitro logs the paths in the terminal:
+```
+ℹ Using app/entry-server.ts as vite ssr entry.
+ℹ Using app/entry-client.ts as vite client entry.
+```
+::
+
+Supported file extensions: `.ts`, `.js`, `.mts`, `.mjs`, `.tsx`, `.jsx`.
+
+### Server entry
+
+The server entry must export an object with a `fetch` method that receives a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response):
+
+```ts [src/entry-server.tsx]
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const html = renderAppToHTML(req);
+    return new Response(html, {
+      headers: { "Content-Type": "text/html;charset=utf-8" },
+    });
+  },
+};
+```
+
+### Client entry
+
+The client entry runs in the browser and hydrates the server-rendered HTML:
+
+```ts [src/entry-client.tsx]
+import { hydrate } from "my-framework";
+import { App } from "./app";
+
+hydrate(document.querySelector("#app"), App);
+```
+
+### Asset management with `?assets` imports
+
+In production, Nitro collects CSS and JS assets from each entry point. Use the `?assets` query to import asset manifests in the server entry:
+
+```ts [src/entry-server.tsx]
+import clientAssets from "./entry-client?assets=client";
+import serverAssets from "./entry-server?assets=ssr";
+
+export default {
+  async fetch(req: Request) {
+    const assets = clientAssets.merge(serverAssets);
+
+    const html = `<!DOCTYPE html>
+    <html>
+      <head>
+        ${assets.css.map((attr) => `<link rel="stylesheet" href="${attr.href}" />`).join("\n")}
+        ${assets.js.map((attr) => `<link rel="modulepreload" href="${attr.href}" />`).join("\n")}
+        <script type="module" src="${assets.entry}"></script>
+      </head>
+      <body>
+        <div id="app">${await renderToString(req)}</div>
+      </body>
+    </html>`;
+
+    return new Response(html, {
+      headers: { "Content-Type": "text/html;charset=utf-8" },
+    });
+  },
+};
+```
+
+The `?assets=client` suffix tells Nitro to collect assets from the client environment, while `?assets=ssr` collects assets from the SSR environment (such as CSS imported only in server components). The `merge()` method combines them into a single manifest with:
+
+- `assets.entry` — the client entry script URL
+- `assets.css` — an array of stylesheet attributes (`{ href }`)
+- `assets.js` — an array of module preload attributes (`{ href }`)
+
+### Framework examples
+
+See working SSR examples for popular frameworks:
+
+| Framework | Example |
+| --- | --- |
+| React | [`vite-ssr-react`](https://github.com/nitrojs/nitro/tree/main/examples/vite-ssr-react) |
+| Vue + Vue Router | [`vite-ssr-vue-router`](https://github.com/nitrojs/nitro/tree/main/examples/vite-ssr-vue-router) |
+| Solid | [`vite-ssr-solid`](https://github.com/nitrojs/nitro/tree/main/examples/vite-ssr-solid) |
+| Preact | [`vite-ssr-preact`](https://github.com/nitrojs/nitro/tree/main/examples/vite-ssr-preact) |
+
 ## Use Cases
 
 ### Single-Page Application (SPA)
@@ -183,6 +288,6 @@ Serve your SPA's `index.html` for all routes to enable client-side routing:
 > [!TIP]
 > This is the default behavior of Nitro when used with Vite.
 
-<!-- ### Server-Side Rendering (SSR) -->
+### Server-Side Rendering (SSR)
 
-<!-- TODO: Add example with ssr-outlet and vite -->
+See [Server-Side Rendering](#server-side-rendering-ssr) for more details.
