{"canonical_url":"https://engineer.company/glossary/server-side-rendering/","content_markdown":"# Server-side rendering\n\n## What it is\n\nServer-side rendering, usually shortened to SSR, means producing a page's HTML\non the server at the moment someone asks for it. The browser receives a complete\ndocument with the content already in place and can show it before any script\nhas run. In a JavaScript framework the same components then run a second time in\nthe browser, which takes over the HTML it was sent and makes it interactive.\n\nThe term answers a question about timing: when, and where, is the HTML made?\nThree answers are common. A static site generator makes it once, at build time,\nand serves the same file to everyone. Server-side rendering makes it on the\nserver for each request, so the page can depend on who is asking and on what\nthe data says at that moment. Client-side rendering, often called CSR, sends a\nnearly empty document and a bundle of JavaScript that builds the page in the\nbrowser. Real applications often mix all three, one route at a time.\n\nNext.js puts it the same way. Its documentation gives dynamic rendering as\nanother name for SSR and says that the page's HTML is generated on each\nrequest. In the Pages Router a page opts in by exporting an async function\ncalled `getServerSideProps`, which the server calls on every request; its\nsibling `getStaticProps` does the same job once, at build time. React supplies\nthe machinery underneath. Its `react-dom/server` APIs turn a tree of components\ninto HTML on the server, either as a stream, with `renderToPipeableStream` for\nNode.js and `renderToReadableStream` for Web Streams, or in one piece with the\nolder `renderToString`, which React lists as a legacy API with limited\nfunctionality.\n\nThe second half happens in the browser and is called hydration. Next.js\ndescribes the first load this way: the HTML gives a fast, non-interactive\npreview, and JavaScript then hydrates the components, which it defines as React\nconnecting the event handlers to the existing DOM so the page responds to input.\nReact's reference for `hydrateRoot` is frank about the trade. The HTML snapshot\nmakes the app appear to load sooner, and the page looks ready a moment before it\nis.\n\n## Why it matters\n\nThe content is in the first response. A reader on a slow connection sees text\nand images while the JavaScript is still on its way, and a crawler that does\nnot run JavaScript sees the same page a person does rather than an empty shell.\nThe browser does not have to run a script and then fetch data before it can\npaint real content.\n\nThe page can also depend on the request, which is what sets it apart from a\nstatic build. Next.js recommends `getServerSideProps` for data that is personal\nto the user or known only at request time, such as an authorization header or\nthe visitor's location, and points everything else towards build-time\ngeneration. The data is fetched next to where it lives. Code inside the\nfunction runs only on the server, its imports are left out of the client\nbundle, and it can query a database or a content management system directly.\nOne trip to the server can replace the requests a browser would otherwise make\none after another once its scripts had loaded.\n\nThe costs mirror a static site's savings. There has to be a running server, and\nit does the rendering work again for every request. The response can start\nonly once the data is there, so without streaming the slowest query sets the\npace for the whole page. And server rendering does not remove the JavaScript:\nthe browser still downloads every component it has to hydrate, and until\nhydration finishes, a button can be drawn on the screen and still do nothing.\n\nThat makes it a choice per page rather than per project. A page that is the\nsame for every reader gains little from being rendered again on every request,\nand a page that changes with the reader, or with data that moves by the minute,\nis where SSR earns its server. This site sits at the static end. Its\n[tech stack](/tech-stack/) is static-first where that fits, so these pages need no request-time application execution, and Hugo builds the site.\n\n## What it looks like in practice\n\nThe page below, written for this article, uses the Pages Router. It lists a\nsigned-in customer's orders, sends a visitor without a session to the sign-in\npage and tells every cache not to keep the result. `readSession` and `db` stand\nfor whatever the application uses for sessions and data.\n\n```jsx\n// pages/orders.js\nexport async function getServerSideProps({ req, res }) {\n  const session = await readSession(req.cookies.session);\n  if (!session) {\n    return { redirect: { destination: \"/sign-in\", permanent: false } };\n  }\n\n  const rows = await db.orders.listFor(session.userId);\n  res.setHeader(\"Cache-Control\", \"no-store\");\n\n  return {\n    props: {\n      orders: rows.map((o) =\u003e ({\n        id: o.id,\n        number: o.number,\n        status: o.status,\n      })),\n    },\n  };\n}\n\nexport default function Orders({ orders }) {\n  return (\n    \u003cul\u003e\n      {orders.map((o) =\u003e (\n        \u003cli key={o.id}\u003e\n          {o.number}: {o.status}\n        \u003c/li\u003e\n      ))}\n    \u003c/ul\u003e\n  );\n}\n```\n\nNext.js runs the function on every request to `/orders`. `req.cookies` is the\nrequest's cookie header, already parsed. A `redirect` with `permanent: false`\nis a temporary redirect rather than a permanent one. Whatever comes back under\n`props` has to survive `JSON.stringify`, and it reaches the browser too, as part\nof the initial HTML, so that React can hydrate the list with the same data the\nserver used. That is why the function maps each row down to the three fields the\npage shows instead of passing the database rows straight through. When a reader\nlater arrives through a `next/link` link, Next.js asks the server to run the\nfunction again and gets the props back as JSON, without a full page load.\n\nIn the founder's current work under NextMariner, the Next.js 16 frontend shows\nthe problem this solves. [Its portfolio\nentry](/portfolio/built-the-next-js-16-frontend-ssr-ssg-and-csr/) starts from an\nauthenticated dashboard that had to feel quick and stay interactive. Fetching\neverything in the browser makes the first load drag and brings the N+1 pattern\nwith it: each component wakes up and sends its own request, so a single page\nturns into a cascade of round trips. On that dashboard and on the large\ndirectory listings, a factory called `createPrefetchedServerPage` now fetches\nthe page's data on the server and hands it to the client already populated, so\nthe components start with their data instead of each going off to ask for it.\nPages moved onto the factory come up in one round trip instead of a storm of\nthem. The same entry keeps the other two modes where they suit: public pages are\ngenerated statically because they do not change from user to user, and the\ngenuinely interactive parts stay client-rendered. It also documents a\ncache-invalidation strategy for each data request, so the data stays fresh\nwithout fetching again what the app already has.\n\n## Where it goes wrong\n\n**The server and the browser disagree.** Hydration expects the browser's first\nrender to produce the same output as the server's. A component that checks\n`typeof window`, calls `window.matchMedia` while rendering or prints the current\ntime renders one thing on the server and another in the browser. React's list of\ncauses also includes different data on the two sides and stray whitespace inside\nthe root element. At best a mismatch slows hydration down, and at worst event\nhandlers end up attached to the wrong elements, so its reference for\n`hydrateRoot` says plainly: “You should treat mismatches as bugs and fix them.”\nRender the same thing on both sides. Where the browser really must show\nsomething else, render the server's version first and switch in an effect after\nhydration, which costs a second render, and keep `suppressHydrationWarning` for\nan unavoidable difference such as a timestamp, remembering that it works only\none level deep.\n\n**Secrets ride along in the props.** Everything returned as props is written\ninto the initial HTML so that the browser can hydrate, and the Next.js\ndocumentation warns against passing anything sensitive this way. A function\nthat returns a whole user record hands its password hash and internal flags to\nanyone who opens the page source. Return only the fields the page displays, as\nthe example above does.\n\n**A shared cache serves one reader's page to the next.** The Next.js\ndocumentation illustrates caching for server-rendered pages with\n`Cache-Control: public, s-maxage=10, stale-while-revalidate=59`. Copied onto a\npersonalised page, that header invites a content delivery network or a proxy\nin front of the server to keep the response and hand it to whoever asks next.\nRFC 9111 defines `public` as permission for a cache to store a response it\nwould otherwise refuse, and `s-maxage` as a lifetime meant for shared caches;\neither one also lifts the rule that stops a shared cache from reusing a\nresponse to a request that carried an `Authorization` header. A page built\nfrom cookies or credentials needs `private`, which forbids shared caches to\nstore it, or `no-store`, which forbids every cache.\n\n**The slowest query holds up the page.** Rendered in one piece, the page sends\nnothing until every query behind it has returned, so one slow query delays the\nheader, the navigation and everything else. React's streaming renderer splits\nthe page at `\u003cSuspense\u003e` boundaries. It sends the shell, everything outside any\nboundary, as soon as that is ready, with fallbacks in place, then streams each\nremaining part with a small inline script that swaps it in. One catch follows\nfrom sending early: once streaming starts, the status code can no longer\nchange, so a missing record or a failed check has to be settled before the\nshell goes out, and `onShellError` is where an error status is set.\n\n## Further reading\n\n- [Server-side Rendering (SSR)](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering)\n  — Next.js on HTML generated for each request and how `getServerSideProps`\n  differs from `getStaticProps`.\n- [getServerSideProps](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props)\n  — when to use it, what reaches the client in the initial HTML, and caching\n  with `Cache-Control`.\n- [Server React DOM APIs](https://react.dev/reference/react-dom/server) — the\n  streaming and legacy APIs React offers for rendering components to HTML on\n  the server.\n- [hydrateRoot](https://react.dev/reference/react-dom/client/hydrateRoot) — how\n  React takes over server-rendered HTML, and the common causes of hydration\n  mismatches.\n- [renderToPipeableStream](https://react.dev/reference/react-dom/server/renderToPipeableStream)\n  — the shell, `\u003cSuspense\u003e` boundaries and the status-code caveat of streaming.\n- [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html) — the\n  `public`, `private`, `s-maxage` and `no-store` directives and the rules for\n  shared caches.\n\n\u003chttps://engineer.company/glossary/server-side-rendering/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Rendering a page's HTML on the server for every request: how it differs from static and client rendering, hydration, and four ways it leaks or stalls.","formats":{"gemtext":"https://engineer.company/glossary/server-side-rendering/index.gmi","gopher":"https://engineer.company/glossary/server-side-rendering/gophermap","html":"https://engineer.company/glossary/server-side-rendering/","json":"https://engineer.company/glossary/server-side-rendering/index.json","markdown":"https://engineer.company/glossary/server-side-rendering/index.md","pdf":"https://engineer.company/glossary/server-side-rendering/index.pdf"},"kind":"page","language":"en","title":"What is server-side rendering?","url":"https://engineer.company/glossary/server-side-rendering/","version":1}