getServerSideProps

페이지에서 getServerSideProps (서버 사이드 렌더링)이라는 함수를 내보내면, Next.js는 getServerSideProps에서 반환된 데이터를 사용해 각 요청마다 페이지를 사전 렌더링합니다. 이는 자주 변경되는 데이터를 가져오고, 페이지를 최신 데이터로 업데이트하려는 경우 유용합니다.

pages/index.tsx
import type { InferGetServerSidePropsType, GetServerSideProps } from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
export const getServerSideProps = (async () => {
  // 외부 API에서 데이터를 가져옵니다.
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo: Repo = await res.json()
  // props를 통해 페이지에 데이터를 전달합니다.
  return { props: { repo } }
}) satisfies GetServerSideProps<{ repo: Repo }>
 
export default function Page({
  repo,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return (
    <main>
      <p>{repo.stargazers_count}</p>
    </main>
  )
}
pages/index.js
export async function getServerSideProps() {
  // 외부 API에서 데이터를 가져옵니다.
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  // props를 통해 페이지에 데이터를 전달합니다.
  return { props: { repo } }
}
 
export default function Page({ repo }) {
  return (
    <main>
      <p>{repo.stargazers_count}</p>
    </main>
  )
}

getServerSideProps에서 사용하기 위해 상위 레벨 범위에서 모듈을 가져올 수 있습니다. 사용된 임포트는 클라이언트 사이드에 번들되지 않습니다. 이는 데이터베이스에서 데이터를 가져오는 것을 포함해 getServerSideProps 내에서 서버 사이드 코드를 직접 작성할 수 있음을 의미합니다.

Context parameter

context 매개변수는 다음 키를 포함하는 객체입니다:

NameDescription
params이 페이지가 동적 라우트를 사용하는 경우, params에는 라우트 매개변수가 포함됩니다. 페이지 이름이 [id].js면, params{ id: ... }와 같이 표시됩니다.
req추가적인 cookies prop이 있는 The HTTP IncomingMessage 객체 (opens in a new tab)이며, 이는 문자열 값을 가진 쿠키의 문자열 키를 매핑하는 객체입니다.
resThe HTTP response 객체 (opens in a new tab)입니다.
query동적 라우트 매개변수를 포함한 쿼리 문자열을 나타내는 객체입니다.
preview(draftMode로 대체 예정) 페이지가 미리보기 모드에 있는 경우 previewtrue이고, 그렇지 않으면 false입니다.
previewData(draftMode로 대체 예정) setPreviewData에 의해 설정된 미리보기 데이터입니다.
draftMode페이지가 Draft Mode에 있는 경우 draftModetrue이고, 그렇지 않으면 false입니다.
resolvedUrl클라이언트 전환을 위한 _next/data 접두사를 제거하고 원래 쿼리 값을 포함하는 요청 URL의 정규화된 버전입니다.
locale활성 로케일이 포함됩니다. (활성화된 경우)
locales지원되는 모든 로케일이 포함됩니다. (활성화된 경우)
defaultLocale설정된 기본 로케일이 포함됩니다. (활성화된 경우)

getServerSideProps return values

getServerSideProps 함수는 다음 속성 중 하나를 가진 객체를 반환해야 합니다:

props

props 객체는 페이지 컴포넌트가 받는 키-값 쌍입니다. 전달된 모든 props가 JSON.stringify (opens in a new tab)로 직렬화될 수 있도록 직렬화 가능한 객체 (opens in a new tab)여야 합니다.

export async function getServerSideProps(context) {
  return {
    props: { message: `Next.js is awesome` }, // 페이지 컴포넌트에 props로 전달됩니다.
  }
}

notFound

notFound 불리언 값은 페이지가 404 상태와 404 Page를 반환하도록 합니다. notFound: true인 경우, 이전에 성공적으로 생성된 페이지가 있어도 페이지는 404를 반환합니다. 이는 사용자 생성 콘텐츠가 작성자에 의해 제거되는 경우와 같은 사용 사례를 지원하기 위함입니다.

export async function getServerSideProps(context) {
  const res = await fetch(`https://.../data`)
  const data = await res.json()
 
  if (!data) {
    return {
      notFound: true,
    }
  }
 
  return {
    props: { data }, // 페이지 컴포넌트에 props로 전달됩니다.
  }
}

redirect

redirect 객체는 내부 및 외부 리소스로 리디렉션을 허용합니다. 이는 { destination: string, permanent: boolean }의 형태와 일치해야 합니다. 드물게, 이전 HTTP 클라이언트가 제대로 리디렉션되도록 사용자 정의 상태 코드를 할당해야 할 수도 있습니다. 이러한 경우, permanent 속성 대신 statusCode 속성을 사용할 수 있지만, 둘 다 사용할 수는 없습니다.

export async function getServerSideProps(context) {
  const res = await fetch(`https://.../data`)
  const data = await res.json()
 
  if (!data) {
    return {
      redirect: {
        destination: '/',
        permanent: false,
      },
    }
  }
 
  return {
    props: {}, // 페이지 컴포넌트에 props로 전달됩니다.
  }
}

Version History

VersionChanges
v13.4.0App Router가 안정화되었고, 단순화된 데이터 페칭을 지원합니다.
v10.0.0locale, locales, defaultLocale, 및 notFound 옵션이 추가되었습니다.
v9.3.0getServerSideProps가 도입되었습니다.