SSG: getSaticProps

export async function getStaticProps(context) {
  return {
    props: {}, // will be passed to the page component as props
  }
}

If you export a function called getStaticProps (Static Site Generation) from a page, Next.js will pre-render this page at build time using the props returned by getStaticProps.

페이지에서 getStaticProps라는 함수를 export한다면 Next.js는 getStaticProps에서 리턴된 props를 사용해 build time에 페이지를 사전 렌더링할 것이다.

When should I use getStaticProps?

You should use getStaticProps if:

• The data required to render the page is available at build time ahead of a user’s request
• The data comes from a headless CMS
• The page must be pre-rendered (for SEO) and be very fast — getStaticProps generates HTML and JSON files, both of which can be cached by a CDN for performance
• The data can be publicly cached (not user-specific). This condition can be bypassed in certain specific situation by using a Middleware to rewrite the path.

getStaticProps를 사용해야 하는 경우는 다음과 같다.

• 페이지를 렌더링하기 위해 필요한 데이터가 user의 요청 전, build time에 사용 가능할 때
• 데이터가 headless CMS에서 올 때
• 페이지가 SEO를 위해 반드시 사전 렌더링되어야 하고 매우 빨라야 할 때 - getStaticProps가 HTML, JSON 파일을 만드는데 이 둘 모두 성능을 위해 CDN에서 캐시될 수 있다.
• 데이터가 사용자 별이 아닌 공개적으로 캐시될 수 있을 때. 하지만 특정 상황에서 미들웨어를 사용하여 경로를 rewrite하면 이 조건을 무시할 수 있다.

When does getStaticProps run?

getStaticProps always runs on the server and never on the client.

• getStaticProps always runs during next build
• getStaticProps runs in the background when using fallback: true
• getStaticProps is called before initial render when using fallback: blocking
• getStaticProps runs in the background when using revalidate
• getStaticProps runs on-demand in the background when using revalidate()

getStaticProps는 클라이언트가 아닌 서버에서 실행된다.

• getStaticProps는 next build 중 실행된다.
• getStaticProps는 fallback: true일 때 백그라운드에서 실행된다.
• getStaticProps는 fallback: blocking일 때 초기 렌더링 전에 실행된다.
• getStaticProps는 revalidate를 사용할 때 백그라운드에서 실행된다.
• getStaticProps는 revalidate()를 사용할 때 백그라운드에서 on-demand로 실행된다.

When combined with Incremental Static Regeneration, getStaticProps will run in the background while the stale page is being revalidated, and the fresh page served to the browser.

Incremental Static Regeneration과 결합 시 getStaticProps는 오래된 페이지가 재검증되는 동안 항상 백그라운드에서 실행되며 브라우저에 fresh한 페이지를 제공한다.

getStaticProps does not have access to the incoming request (such as query parameters or HTTP headers) as it generates static HTML. If you need access to the request for your page, consider using Middleware in addition to getStaticProps.

getStaticProps는 정적 HTML을 생성하므로 앞으로 있을 request(query나 HTTP 헤더)에 접근할 수 없다.
만약 페이지를 렌더링하기 위해 request에 접근해야 한다면 getStaticProps와 middleware를 함께 사용하는 것을 고려해야 한다.

Using getStaticProps to fetch data from a CMS

// posts will be populated at build time by getStaticProps()
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// This function gets called at build time on server-side.
// It won't be called on client-side, so you can even do
// direct database queries.
export async function getStaticProps() {
  // Call an external API endpoint to get posts.
  // You can use any data fetching library
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // By returning { props: { posts } }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts,
    },
  }
}

export default Blog

Write server-side code directly

As getStaticProps runs only on the server-side, it will never run on the client-side. It won’t even be included in the JS bundle for the browser, so you can write direct database queries without them being sent to browsers.

getStaticProps가 서버에서만 실행되기 때문에 클라이언트에서는 절대 실행되지 않는다.
브라우저의 JS 번들에도 포함되지 않으므로 브라우저에 보내지 않고 직접 데이터베이스 쿼리를 작성할 수 있다.

This means that instead of fetching an API route from getStaticProps (that itself fetches data from an external source), you can write the server-side code directly in getStaticProps.

다시 말해, getStaticProps에서 api 경로를 fetching하는 것(외부에서 데이터를 가져오는 것) 대신에 서버측 코드에 getStaticProps를 직접 쓸 수 있다.

Take the following example. An API route is used to fetch some data from a CMS. That API route is then called directly from getStaticProps. This produces an additional call, reducing performance. Instead, the logic for fetching the data from the CMS can be shared by using a lib/ directory. Then it can be shared with getStaticProps.

다음 예제를 보면 API 경로는 CMS로부터 데이터를 가져오는데 이 API 경로는 getStaticProps에서 호출되고 있다.
이러한 절차는 추가적인 호출을 발생시켜 성능을 저하시킨다.

대신, CMS에서 데이터를 가져오는 로직을 lib/ 디렉터리에서 사용하면 getStaticProps와 공유할 수 있다.

// lib/load-posts.js

// The following function is shared
// with getStaticProps and API routes
// from a `lib/` directory
export async function loadPosts() {
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

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

// This function runs only on the server side
export async function getStaticProps() {
  // Instead of fetching your `/api` route you can call the same
  // function directly in `getStaticProps`
  const posts = await loadPosts()

  // Props returned will be passed to the page component
  return { props: { posts } }
}

Alternatively, if you are not using API routes to fetch data, then the fetch() API can be used directly in getStaticProps to fetch data.

또는 API 경로를 사용하여 데이터를 가져오지 않는 경우 fetch API를 getStaticProps에서 직접 사용해 데이터를 가져올 수 있다.

Statically generates both HTML and JSON

When a page with getStaticProps is pre-rendered at build time, in addition to the page HTML file, Next.js generates a JSON file holding the result of running getStaticProps.

build time에 getStaticProps가 포함된 페이지가 사전 렌더링될 때, 페이지의 HTML 파일 외에도 Next.js는 getStaticProps의 결과를 담고있는 JSON 파일을 만든다.

This JSON file will be used in client-side routing through next/link or next/router. When you navigate to a page that’s pre-rendered using getStaticProps, Next.js fetches this JSON file (pre-computed at build time) and uses it as the props for the page component. This means that client-side page transitions will not call getStaticProps as only the exported JSON is used.

JSON 파일은 next/link나 next/router를 통한 클라이언트 측의 라우팅에 사용된다.
만약 getStaticProps를 이용해 사전 렌더링된 페이지로 이동할 경우, Next.js는 JSON 파일을 가져와 page component의 props로 사용한다.
즉, 클라이언트 측의 페이지 전환은 getStaticProps를 호출하지 않고 export된 JSON을 사용한다.

When using Incremental Static Generation, getStaticProps will be executed in the background to generate the JSON needed for client-side navigation. You may see this in the form of multiple requests being made for the same page, however, this is intended and has no impact on end-user performance.

Incremental Static Generation을 사용할 때 getStaticProps는 클라이언트 측의 navigation에 필요한 JSON을 만들기 위해 백그라운드에서 실행될 것이다.
동일한 페이지에 여러 요청이 이루어지는 형태로 볼 수 있지만, 사용자 성능에는 영향을 주지 않는다.

Where can I use getStaticProps

getStaticProps can only be exported from a page. You cannot export it from non-page files, _app, _document, or _error.

getStaticProps는 오직 page에서만 export될 수 있다.
따라서 페이지 파일이 아니거나 _app, _document, _error에서는 사용할 수 없다.

One of the reasons for this restriction is that React needs to have all the required data before the page is rendered.

이러한 제한의 이유 중 하나는 페이지가 렌더링되기 전에 React는 필요한 데이터가 있어야 하기 때문이다.

Also, you must use export getStaticProps as a standalone function — it will not work if you add getStaticProps as a property of the page component.

또한 getStaticProps를 독립 함수로 사용해야 한다.
만약 page component의 property로 getStaticProps를 사용하면 동작하지 않을 것이다.

Runs on every request in development

In development (next dev), getStaticProps will be called on every request.

개발 환경(next dev)에서, getStaticProps는 매 요청마다 호출될 것이다.