getServerSideProps

getServerSideProps는 요청 시 데이터 가져오기와 페이지 콘텐츠를 렌더링하는 데 사용할 수 있는 Next.js 함수입니다.

Example

getServerSideProps를 Page Component에서 export하여 사용할 수 있습니다. 아래 예제는 getServerSideProps에서 서드파티 API로부터 데이터를 가져오고, 그 데이터를 props로 페이지에 전달하는 방법을 보여줍니다:

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>
  )
}

When should I use `getServerSideProps`?

개인화된 사용자 데이터나 요청 시에만 알 수 있는 정보에 의존하는 페이지를 렌더링해야 하는 경우 getServerSideProps를 사용해야 합니다. 예를 들어, authorization 헤더나 지리적 위치 정보가 있습니다.

요청 시 데이터 가져오기가 필요 없거나, 데이터를 캐시하고 미리 렌더된 HTML을 선호하는 경우 getStaticProps 사용을 권장합니다.

Behavior

getServerSideProps는 서버에서 실행됩니다.
getServerSideProps는 페이지에서만 export할 수 있습니다.
getServerSideProps는 JSON을 반환합니다.
사용자가 페이지를 방문할 때 getServerSideProps가 데이터를 요청 시 가져와서 페이지의 초기 HTML을 렌더링하는 데 사용됩니다.
페이지 컴포넌트에 전달된 props는 초기 HTML의 일부로 클라이언트에서 볼 수 있습니다. 이는 페이지가 hydrated (opens in a new tab) 될 수 있도록 하기 위함입니다. props에 클라이언트에서 볼 수 없어야 하는 민감한 정보를 전달하지 않도록 주의하세요.
사용자가 next/link 또는 next/router를 통해 페이지를 방문하면 Next.js가 서버에 API 요청을 보내 getServerSideProps를 실행합니다.
getServerSideProps를 사용할 때 데이터를 가져오기 위해 Next.js API Route를 호출할 필요가 없습니다. 대신, getServerSideProps 내부에서 CMS, 데이터베이스 또는 다른 서드파티 API를 직접 호출할 수 있습니다.

알아두면 좋은 점:

getServerSideProps에서 사용할 수 있는 매개변수와 props에 대한 자세한 내용은 getServerSideProps API reference를 참조하세요.

next-code-elimination tool (opens in a new tab)을 사용하여 Next.js가 클라이언트 측 번들에서 제거하는 내용을 확인할 수 있습니다.

Error Handling

getServerSideProps 내에서 오류가 발생하면 pages/500.js 파일이 표시됩니다. 500 페이지를 만드는 방법에 대해 자세히 알아보려면 500 page 문서를 확인하세요. 개발 중에는 이 파일이 사용되지 않고 개발 오류 오버레이가 대신 표시됩니다.

Edge Cases

Caching with Server-Side Rendering (SSR)

getServerSideProps 내부에서 캐싱 헤더(Cache-Control)를 사용하여 동적 응답을 캐시할 수 있습니다. 예를 들어, stale-while-revalidate (opens in a new tab)를 사용할 수 있습니다.

// 이 값은 10초 동안 신선한 것으로 간주됩니다 (s-maxage=10).
// 다음 10초 내에 요청이 반복되면 이전에 캐시된 값이 여전히 신선합니다.
// 요청이 59초 전에 반복되면 캐시된 값이 오래되었지만 여전히 렌더링됩니다 (stale-while-revalidate=59).
// 백그라운드에서 재검증 요청이 이루어져 새 값으로 캐시를 채웁니다.
// 페이지를 새로 고치면 새 값을 볼 수 있습니다.
export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59',
  )
 
  return {
    props: {},
  }
}

그러나 cache-control을 사용하기 전에 getStaticProps와 ISR이 사용 사례에 더 적합한지 확인하는 것을 권장합니다.

Forms and Mutations Incremental Static Regeneration