함수: getInitialProps

함수: getInitialProps | Next.js

출처 URL: https://nextjs.org/docs/pages/api-reference/functions/get-initial-props

getInitialProps

마지막 업데이트: 2026년 2월 20일

알아두면 좋아요 : getInitialProps는 레거시 API입니다. 대신 getStaticProps 또는 getServerSideProps를 사용하는 것을 권장합니다.

getInitialProps는 페이지에 기본으로 export되는 React 컴포넌트에 추가할 수 있는 async 함수입니다. 이 함수는 서버 측과 페이지 전환 중의 클라이언트 측에서 모두 실행되며, 함수의 반환값은 props로 React 컴포넌트에 전달됩니다.

pages/index.tsx

JavaScriptTypeScript

    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
    }

알아두면 좋아요 :

• getInitialProps에서 반환된 데이터는 서버 렌더링 시 직렬화됩니다. getInitialProps에서 반환하는 객체는 순수한 Object여야 하며 Date, Map, Set을 사용하지 않아야 합니다.
• 초기 페이지 로드 시 getInitialProps는 서버에서만 실행됩니다. 이후 next/link 컴포넌트로 다른 경로로 이동하거나 next/router를 사용할 때 클라이언트에서도 실행됩니다.
• 커스텀 _app.js에서 getInitialProps를 사용하고, 이동하려는 페이지가 getServerSideProps를 사용한다면 getInitialProps는 서버에서만 실행됩니다.

Context Object

getInitialProps는 context라고 불리는 단일 인수를 받으며, 이 객체는 다음 속성들을 포함합니다:

Name	Description
pathname	현재 라우트, /pages 내 페이지의 경로
query	URL의 쿼리 문자열을 객체로 파싱한 값
asPath	브라우저에 표시되는 실제 경로(쿼리 포함)의 String 값
req	HTTP request object (서버 전용)
res	HTTP response object (서버 전용)
err	렌더링 중 오류가 발생한 경우의 에러 객체

주의사항

• getInitialProps는 pages/ 최상위 파일에서만 사용할 수 있으며, 중첩된 컴포넌트에서는 사용할 수 없습니다. 컴포넌트 수준에서 중첩 데이터 패칭이 필요하다면 App Router를 검토하세요.
• 라우트가 정적이든 동적이든 관계없이, getInitialProps에서 props로 반환된 모든 데이터는 초기 HTML에서 클라이언트 측에서 확인할 수 있습니다. 이는 페이지가 올바르게 hydrate되도록 하기 위한 것입니다. 클라이언트에서 볼 수 없어야 하는 민감한 정보를 props로 전달하지 않도록 주의하세요.

보내기