getInitialProps

알아두기 : getInitialProps는 레거시 API입니다. 대신 getStaticProps 또는 getServerSideProps를 사용하는 것이 좋습니다.

getInitialProps는 페이지에 기본적으로 내보내지는 React 컴포넌트에 추가할 수 있는 비동기 함수입니다. 이 함수는 서버 사이드와 클라이언트 사이드의 페이지 전환 시 모두 실행됩니다. 함수의 결과는 React 컴포넌트에 props로 전달됩니다.

pages/index.tsx

import { NextPageContext } from 'next'
 
Page.getInitialProps = async (ctx: NextPageContext) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const json = await res.json()
  return { stars: json.stargazers_count }
}
 
export default function Page({ stars }: { stars: number }) {
  return stars
}

pages/index.js

Page.getInitialProps = async (ctx) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const json = await res.json()
  return { stars: json.stargazers_count }
}
 
export default function Page({ stars }) {
  return stars
}

알아두기:

getInitialProps에서 반환된 데이터는 서버 렌더링 시 직렬화됩니다. getInitialProps에서 반환하는 객체는 단순한 Object여야 하며, Date, Map, Set 같은 객체를 사용하지 않아야 합니다.

초기 페이지 로드 시, getInitialProps는 서버에서만 실행됩니다. 이후에는 next/link 컴포넌트나 next/router를 사용하여 다른 경로로 이동할 때 클라이언트에서도 getInitialProps가 실행됩니다.

getInitialProps가 사용자 정의 _app.js에서 사용되며, 이동하려는 페이지가 getServerSideProps를 사용하는 경우, getInitialProps는 서버에서도 실행됩니다.

Context Object

getInitialProps는 context라는 단일 인자를 받습니다. 이 context는 다음과 같은 속성을 가진 객체입니다:

이름	설명
`pathname`	현재 경로, `/pages` 디렉토리 내의 페이지 경로
`query`	URL의 쿼리 문자열을 객체로 파싱한 값
`asPath`	브라우저에 표시되는 실제 경로(query 포함)의 `문자열`
`req`	HTTP 요청 객체 (opens in a new tab) (서버 전용)
`res`	HTTP 응답 객체 (opens in a new tab) (서버 전용)
`err`	렌더링 중 오류가 발생할 경우 오류 객체

Caveats

getInitialProps는 pages/ 디렉토리의 최상위 파일에서만 사용할 수 있으며, 중첩된 컴포넌트에서는 사용할 수 없습니다. 컴포넌트 수준에서 중첩된 데이터 가져오기를 하려면 App Router를 참고해 보세요.
경로가 정적이든 동적이든 상관없이, getInitialProps에서 반환된 데이터는 초기 HTML에서 클라이언트 단에서 확인할 수 있습니다. 이는 페이지가 hydrated (opens in a new tab)될 수 있도록 하기 위해서입니다. 클라이언트에서 접근하면 안 되는 민감한 정보는 props에 포함되지 않도록 주의하세요.

Functions getServerSideProps