getServerSideProps API

If you export an async function called getServerSideProps from a page, Blitz will pre-render this page on each request using the data returned by getServerSideProps.

export async function getServerSideProps(context) {
  return {
    props: {}, // will be passed to the page component as props
  }
}

The context parameter is an object containing the following keys:

params: If this page uses a dynamic route, params contains the route parameters. If the page name is [id].js , then params will look like { id: ... }. To learn more, take a look at the Dynamic Routing documentation.
req: The HTTP IncomingMessage object.
res: The HTTP response object.
query: The query string.
preview: preview is true if the page is in the preview mode and false otherwise. See the Preview Mode documentation.
previewData: The preview data set by setPreviewData. See the Preview Mode documentation.
resolvedUrl: A normalized version of the request URL that strips the _next/data prefix for client transitions and includes original query values.
locale contains the active locale (if enabled).
locales contains all supported locales (if enabled).
defaultLocale contains the configured default locale (if enabled).

getServerSideProps should return an object with:

props - A required object with the props that will be received by the page component. It should be a serializable object

notFound - An optional boolean value to allow the page to return a 404 status and page. Below is an example of how it works:

export async function getServerSideProps(context) {
  const data = /* ... */

  if (!data) {
    return {
      notFound: true,
    }
  }

  return {
    props: {}, // will be passed to the page component as props
  }
}

redirect - An optional redirect value to allow redirecting to internal and external resources. It should match the shape of { destination: string, permanent: boolean }. In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the statusCode property instead of the permanent property, but not both. Below is an example of how it works:
```
export async function getServerSideProps(context) {
  const data = /* ... */

  if (!data) {
    return {
      redirect: {
        destination: "/",
        permanent: false,
      },
    }
  }

  return {
    props: {}, // will be passed to the page component as props
  }
}
```

Note: You can import modules in top-level scope for use in getServerSideProps. Imports used in getServerSideProps will not be bundled for the client-side.
This means you can write server-side code directly in getServerSideProps. This includes reading from the filesystem or a database.

Simple example

Here’s an example which uses getServerSideProps to fetch data at request time and pre-renders it.

function Page({data}) {
  // Render data...
}

// This gets called on every request
export async function getServerSideProps() {
  const data = /* ... */

  // Pass data to the page via props
  return {props: {data}}
}

export default Page

When should I use `getServerSideProps`?

You should use getServerSideProps only if you need to pre-render a page whose data must be fetched at request time. Time to first byte (TTFB) will be slower than getStaticProps because the server must compute the result on every request, and the result cannot be cached by a CDN without extra configuration.

If you don’t need to pre-render the data, then you should consider fetching data on the client side. Click here to learn more.

TypeScript: Use `GetServerSideProps`

For TypeScript, you can use the GetServerSideProps type from blitz:

import { GetServerSideProps } from "blitz"

export const getServerSideProps: GetServerSideProps = async (context) => {
  // ...
}

If you want to get inferred typings for your props, you can use InferGetServerSidePropsType<typeof getServerSideProps>, like this:

import { InferGetServerSidePropsType } from 'blitz'

type Data = { ... }

export const getServerSideProps = async () => {
  const data: Data = /* ... */

  return {
    props: {
      data,
    },
  }
}

function Page({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {
  // will resolve posts to type Data
}

export default Page

Technical details

Only runs on server-side

getServerSideProps only runs on server-side and never runs on the browser. If a page uses getServerSideProps , then:

When you request this page directly, getServerSideProps runs at the request time, and this page will be pre-rendered with the returned props.
When you request this page on client-side page transitions through <Link> or router (documentation), Blitz sends an API request to the server, which runs getServerSideProps. It’ll return JSON that contains the result of running getServerSideProps, and the JSON will be used to render the page. All this work will be handled automatically by Blitz, so you don’t need to do anything extra as long as you have getServerSideProps defined.

You can use this tool to verify what Blitz eliminates from the client-side bundle.

Only allowed in a page

getServerSideProps can only be exported from a page. You can’t export it from non-page files.

Also, you must use export async function getServerSideProps() {} — it will not work if you add getServerSideProps as a property of the page component.

First Render UX

Even though a page with getServerSideProps will be pre-rendered on the server, it may fallback to the page's loading state if your page contains queries that request data missing from the initial page props. This can create a flickering effect where the contents of the page rapidly changes when the query data gets loaded into the app.

Click here to discover ways you can improve the first render User Experience (UX) of your pages.