Next.js - getStaticProps 공식문서 번역

2022/10/31

n°24

category : Next.js

개인적으로 공부하기 위해 Next.js docs의 getStaticProps를 번역했습니다. 오역/의역이 있을 수 있습니다. leetekwoo@gmail.com으로 언제든 피드백 주세요!

getStaticProps

페이지 내에서 getStaticProps(정적 사이트 생성 SSG)라는 이름의 함수를 export한다면, next.js는 getStaticProps 함수의 반환값을 사용하여 빌드 타임에 그 페이지를 사전 렌더링pre-render합니다.

 export async function getStaticProps(context) {
  return {
    props: {}, // 이 부분은 페이지 컴포넌트의 props로 전달됩니다.  }
}

렌더링 타입과 상관없이 모든 props는 페이지 컴포넌트로 전달되어 클라이언트의 초기 HTML에서 보여질 수 있습니다. 이는 페이지가 올바르게 hydrate 되도록 하기 위함입니다. 클라이언트에서 보여지면 안되는 민감한 정보를 props로 전달하지 않도록 주의하십시오.

When should I use getStaticProps?

언제 getStaticProps를 사용할까?

페이지를 렌더하기 위한 데이터가 유저의 요청 이전의 빌드 타임에 접근할 수 있는 경우
데이터가 headless CMS로부터 오는 경우
페이지가 SEO를 위해 pre-render 되어야 하거나 매우 빨라야 하는 경우 - getStaticProps는 성능 개선을 위한 CDN으로 캐싱될 수 있는 HTML과 JSON 파일을 생성합니다.
유저 특정적이지 않은 데이터가 공개적으로 캐싱될 수 있는 경우. 이 조건은 특정 한 상황에서 경로를 rewrite 하기 위한 미들웨어를 사용하여 우회할 수 있습니다.

When does getStaticProps run

getStaticProps는 언제 실행되는가

getStaticProps는 항상 서버에서 실행되고, 절대 클라이언트에서 실행되지 않습니다. 이 툴을 사용하여 getStaticProps 내부에 작성된 코드가 클라이언트 사이드의 번들에서 삭제되었는지 검증할 수 있습니다.

getStaticProps는 항상 next build 동안에 실행됩니다.
getStaticProps는 "fallback:true"를 사용할 때 항상 백그라운드에서 실행됩니다.
getStaticProps는 "fallback:blocking"을 사용할 시 초기 렌더 이전에 호출됩니다.
getStaticProps는 "revalidate"를 사용할 시 백그라운드에서 실행됩니다.
getStaticProps는 "revalidate()"를 사용할 시 백그라운드에서 온디맨드 방식으로 실행됩니다.

증분 정적 생성 Incremental Static Regeneration(ISR)과 함께 사용될 시 getStaticProps는 오래된 페이지가 revalidate되는 동안 백그라운드에서 실행되고, 새로운 페이지가 브라우저에 제공됩니다. getStaticProps는 정적 HTML을 생성하기 때문에 쿼리 파라미터나 HTTP 헤더와 같은 요청에 접근할 수 없습니다. 페이지에 요청에 접근해야 한다면 미들웨어Middleware 와 함께 getStaticProps를 사용할 것을 고려하십시오.

Using getStaticProps to fetch data from a CMS

getStaticProps를 사용하여 CMS에서 데이터 가져오기

다음 예시는 CMS로부터 블로그의 포스팅 리스트를 가져오는 방법을 보여줍니다.

// posts는 getStaticProps() 함수로 빌드 타임에 채워질 것입니다.

function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// 이 함수는 서버 사이드에서 빌드 타임에 호출됩니다.
// 이는 클라이언트 사이드에서 호출되지 않기 때문에  직접 db 쿼리를 수행할 수 있습니다.

export async function getStaticProps() {
  // post를 얻기 위해 외부 API 엔드포인트를 호출합니다.
  // 모든 data fetching 라이브러리를 사용할 수 있습니다.

  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // { props: { posts } }를 반환하여 Blog 컴포넌트는 빌드 타임에 props로 posts를 받을 수 있습니다.

  return {
    props: {
      posts,
    },
  }
}

export default Blog

getStaticProps API reference는 getStaticProps와 함께 사용될 수 있는 모든 매개변수와 props를 다루고 있습니다.

Write server-side code directly

서버 사이드 코드를 직접 작성하기

getStaticProps는 서버 사이드에서 실행되기 때문에 클라이언트 사이드에서 실행되지 않습니다. 이는 브라우저를 위한 JS 번들에 포함되지 않을 것이므로, 브라우저에 보내질 필요 없이 직접 데이터베이스 쿼리를 작성할 수 있습니다. 즉 (그 자체로 외부 소스로 데이터를 가져오는) getStaticProps에서 API 경로를 가져오는 대신, 서버 사이드 코드를 getStaticProps에 직접 쓸 수 있습니다.

다음 예시를 봅시다. API 경로는 CMS로부터 데이터를 가져오기 위해 사용됩니다. 그리고 이 API 경로는 getStaticProps에서 직접 호출됩니다. 이는 추가적인 호출을 발생시키고 성능 저하로 이어집니다. CMS로부터 데이터를 가져오는 로직은 lib/ 경로를 사용하여 재사용될 수 있습니다. 그러면 이는 getStaticProps에서 재사용될 수 있습니다.

// lib/load-posts.js

// 이 함수는 /lib 경로에서 getStaticProps와 api 경로에 공유됩니다.

export async function loadPosts() {
  //posts를 얻기 위한 외부 API 엔드포인트를 호출합니다.
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// 이 함수는 서버 사이드에서만 실행됩니다.

export async function getStaticProps() {
 // /api 경로를 가져오는 대신에 getStaticProps에서 동일한 //함수를 직접 호출할 수 있습니다.

  const posts = await loadPosts()

  // 반환된 props는 페이지 컴포넌트로 전달될 것입니다.
  return { props: { posts } }
}

데이터를 가져오기 위해 API 경로를 사용하지 않는다면, getStaticProps에서 데이터를 가져오기 위해 직접 fetch() API를 사용할 수 있습니다. 클라이언트 사이드의 번들에서 Next.js가 무엇을 제거하는지 확인하려면, next-code-elimination 툴을 사용하면 됩니다.

Statically generates both HTML and JSON

HTML과 JSON을 정적으로 생성하기

getStaticProps가 있는 페이지가 빌드 타임에 pre-render될 때, Next.js는 페이지의 HTML 파일과 함께 실행된 getStaticProps의 결과를 갖고 있는 JSON 파일을 생성합니다.

이 JSON 파일은 클라이언트 사이드에서 next/link 혹은 next/router를 통한 라우팅에 사용됩니다. getStaticProps를 사용하여 pre-rendered된 페이지로 이동할 때 Next.js는 (빌드 타임에 pre-computed된) 이 JSON 파일을 가져오고, 페이지 컴포넌트의 props로 사용합니다. 즉 export된 JSON만 사용되기 때문에 클라이언트 사이드의 페이지 전환은 getStaticProps를 호출하지 않습니다.

증분 정적 생성(ISR)을 사용할 때, getStaticProps는 클라이언트 사이드의 네비게이션에 필요한 JSON을 생성하기 위해 백그라운드에서 실행될 것입니다. 이는 동일한 페이지에서 여러 번의 요청이 이루어지는 것으로 확인될 수 있습니다. 하지만 이는 의도된 것이며, 최종 사용자의 성능에 영향을 주지 않습니다.

Where can I use getStaticProps

어디에서 getStaticProps가 사용될 수 있는가

getStaticProps는 'page'에서만 export될 수 있습니다. page가 아닌 파일, _app, _document, 혹은 _error에서는 export할 수 없습니다. 이러한 제약의 이유 중 하나는 React에서 페이지가 렌더링되기 전에 필요한 모든 데이터를 갖고 있어야 하기 때문입니다. 또한 getStaticProps는 반드시 독립된 함수로 export 되어야 합니다. 만약 getStaticProps를 페이지 컴포넌트의 속성으로 추가한다면 작동하지 않을 것입니다.

노트: 만일 커스텀 앱(_app)을 사용한다면, 연결된 문서에서처럼 pageProps를 페이지 컴포넌트로 전달하는지 확인하십시오. 그렇지 않다면 props는 비어있을 것입니다.

Runs on every request in development

개발 중 모든 요청에 실행

개발 중 (next dev)에 getStaticProps는 모든 요청에 실행될 것입니다.

Preview Mode

Preview mode를 사용하여 일시적으로 정적 생성을 우회하고 빌드 타임 대신 요청 타임에 페이지를 렌더링할 수 있습니다. 예를 들어 headless CMS를 사용하여 페이지가 공개되기 이전에 초안을 미리볼 수 있습니다.