getServerSideProps executes on the server for every request, with full access to the request/response objects and Node.js runtime, returning serializable props that are used to pre-render the page HTML before sending to the client
Internally, getServerSideProps is a Next.js function designed for Server-Side Rendering (SSR) that runs exclusively on the server at request time. When a request hits a page with getServerSideProps, Next.js executes this function first, providing it with rich context about the request. The function can perform any server-side operations—database queries, API calls, authentication checks—and must return a serializable object. Next.js then uses the returned props to render the React component to HTML on the server, sending the fully-formed page to the client. This entire process happens synchronously per request, ensuring the page always reflects the latest data.
params: Contains dynamic route parameters. For a page named [id].js, params will be { id: 'value' }.
req: The HTTP IncomingMessage object with an additional cookies property for accessing cookies as key-value pairs.
res: The HTTP response object, allowing you to set headers, cookies, or status codes directly.
query: An object containing the query string parameters plus any dynamic route parameters.
draftMode: Boolean indicating if draft mode is enabled (replaces deprecated preview/previewData).
resolvedUrl: Normalized URL string without the _next/data prefix.
locale/locales/defaultLocale: Available when i18n is configured.
When a request arrives, Next.js checks if the page exports getServerSideProps. If yes, it enters SSR mode: First, it calls getServerSideProps with the context object populated from the request. The function executes in a Node.js environment with full server capabilities—direct database access, file system operations, or internal API calls are all safe here because this code never reaches the client. Next.js then awaits the returned promise, expecting an object with props, notFound, or redirect. If props are returned, Next.js serializes them with JSON.stringify and passes them to the page component for rendering on the server. The complete HTML is generated and sent to the client, with the props also embedded in a script tag for hydration.
Server-only execution: Code inside getServerSideProps never reaches the client bundle. You can safely use environment variables, database connections, and file system APIs.
Request-scoped: Runs on every request, not cached. Each user gets fresh data tailored to their specific request context.
Node.js runtime: Full Node.js API access (in default setup). This means you can use fs, read from disk, or connect to databases directly.
Not bundled for client: All imports used only in getServerSideProps are automatically tree-shaken from client bundles.
Serializable requirement: Props must be JSON-serializable because they're embedded in the HTML for client hydration.
Timing: Executes before page render, blocking the response until complete. Long-running operations delay page load.
When users navigate between pages using next/link or next/router, getServerSideProps still runs on the server, but the mechanism differs slightly. Next.js makes a lightweight API request to _next/data/development/{url}.json (or production equivalent) which triggers getServerSideProps execution and returns only the JSON props, not the full HTML. The client then uses these props to render the page without a full reload, maintaining SPA-like navigation while still fetching fresh data per request. This is why you can't have loading states inside getServerSideProps—it's a blocking function that must complete before navigation finishes.
Page-only export: getServerSideProps can only be exported from page files (not components, not API routes).
No client-side data: Never put sensitive data in props—they're embedded in HTML and visible in page source.
Error handling: Thrown errors show the 500.js page in production, with error overlay in development.
No getStaticProps mixing: Cannot use both getServerSideProps and getStaticProps on the same page.
Performance consideration: Each request triggers server execution, which can increase response times and server load.
Development vs Production: In dev mode, getServerSideProps runs on every request regardless of caching headers.
Choose getServerSideProps when you absolutely need request-time data—authenticated content, personalized pages, or data that changes faster than you can rebuild. It's perfect for dashboards, user profiles, and any page where the content is different for every visitor. However, for public content that changes less frequently, prefer getStaticProps with ISR—you'll get similar freshness with much better performance and lower server costs. And if the page doesn't need initial data at all, consider client-side fetching after a static shell for the best balance of performance and freshness.