Next.js getServerSideProps(): Tutorial & Example

Updated: March 22, 2023 By: Goodman Post a comment

Table Of Contents

1 Overview

1.1 General Syntax

1.2 Return Value & Parameters

Overview

getServerSideProps() is a Next.js asynchronous function that can be exported from a page component (in your pages folder) to fetch data at the requested time on the server side before rendering the page. It is useful for dynamic pages that require data that cannot be determined at build time.

General Syntax

In the vast majority of cases, the usage of the getServerSideProps() function will look like this:

export async function getServerSideProps(context) {
  // Fetch data from an external API or database
  const data = await fetch('your API endpoint')
  const jsonData = await data.json()

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

Return Value & Parameters

getServerSideProps() should return an object with one of these properties: props, notFound, or redirect. The props property is an object that will be passed to the page component as props. The notFound property is a boolean that allows the page to return a 404 status and page. The redirect property is an object that allows the page to redirect to another URL with a specific status code.

getServerSideProps() receives a context parameter that contains useful information about the request:

context.params: If this page uses a dynamic route, the params property contains the route parameters.
context.req: The HTTP IncomingMessage object, with an additional cookies prop, which is an object with string keys mapping to string values of cookies.

context.res: The HTTP response object.
context.query: An object representing the query string, including dynamic route parameters.
context.preview: preview is true if the page is in the Preview Mode and false otherwise.

context.previewData: The preview data set by setPreviewData().
context.resolvedUrl: A normalized version of the request URL that strips the _next/data prefix for client transitions and includes original query values.
context.locale contains the active locale (if enabled).

context.locales contains all supported locales (if enabled).
context.defaultLocale contains the configured default locale (if enabled).

Important Notes

Some key points you should know before using the getServerSideProps() function:

getServerSideProps() only runs on the server side and never on the browser. It runs every time you request the page, either directly or through client-side transitions.
You can import modules in top-level scope for use in getServerSideProps(). Imports used will not be bundled for the client side. This means you can write server-side code directly in getServerSideProps(), including fetching data from your database.
You should use getServerSideProps() only if you need to render a page whose data must be fetched at request time. This could be due to the nature of the data or properties of the request (such as authorization headers or geolocation). Pages using getServerSideProps() will be server-side rendered at request time and only be cached if cache-control headers are configured.

You should avoid calling API routes from getServerSideProps(), as it will cause an extra request to be made due to both functions running on the server. Instead, directly import the logic used inside your API route into getServerSideProps().

Complete Example

App Preview

This example will render a page with some information about a user on each request by using the data returned by the getServerSideProps() function. We will fetch data from the following REST API endpoint:

https://api.slingacademy.com/v1/sample-data/users/[id]

The user id is in the range from 1 to 1000.

The final result will look like this (if you look closely you will see that every time we change the id the content of the page changes too):

You can find more details about this API endpoint on this page: Sample Users – Free Fake API for Practicing & Prototyping.

Writing Code

In the pages folder of your Next.js project, create a new folder named users. Inside this folder, create a new file called [id].js, then add the following code to it:

// pages/users/[id].js

export default function User({ user }) {
  // Render user data
  return (
    <div style={{ width: '100%', height: '100vh', padding: 50 }}>
      <p>First Name {user.first_name}</p>
      <p>Last Name: {user.last_name}</p>
      <p>Job: {user.job}</p>
      <p>Email: {user.email}</p>
      <p>Phone: {user.phone}</p>
      <p>Country: {user.country}</p>
    </div>
  );
}

export async function getServerSideProps(context) {
  const { params } = context;
  const { id } = params;
  const URL = `https://api.slingacademy.com/v1/sample-data/users/${id}`;

  // Fetch data from external API
  const res = await fetch(URL);
  const data = await res.json();
  const user = data.user;

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

Run your project: