Data Fetching in Next.js - getStaticPaths

SSG: getStaticPaths

If a page has Dynamic Routes and uses getStaticProps, it needs to define a list of paths to be statically generated.

When you export a function called getStaticPaths (Static Site Generation) from a page that uses dynamic routes, Next.js will statically pre-render all the paths specified by getStaticPaths.

만약 page가 동적 경로를 가지고 있고 getStaticProps를 사용한다면 정적으로 생성될 경로들을 정의할 필요가 있다.

동적 경로를 사용하는 페이지에서 getStaticPaths라는 함수를 export할 때, Next.js는 getStaticPaths에서 명시된 모든 경로를 정적으로 사전 렌더링할 것이다.

// pages/posts/[id].js

// Generates `/posts/1` and `/posts/2`
export async function getStaticPaths() {
  return {
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    fallback: false, // can also be true or 'blocking'
  }
}

// `getStaticPaths` requires using `getStaticProps`
export async function getStaticProps(context) {
  return {
    // Passed to the page component as props
    props: { post: {} },
  }
}

export default function Post({ post }) {
  // Render post...
}

When should I use getStaticPaths?

You should use getStaticPaths if you’re statically pre-rendering pages that use dynamic routes and:

• The data comes from a headless CMS
• The data comes from a database
• The data comes from the filesystem
• The data can be publicly cached (not user-specific)
• 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

동적 경로를 사용한 페이지를 사전 렌더링하는 경우 getStaticPaths를 사용할 수 있다.
getStaticProps와 함께 쓰이기 때문에 getStaticPaths를 사용하는 경우는 getStaticProps와 동일하다.

When does getStaticPaths run

getStaticPaths will only run during build in production, it will not be called during runtime.

getStaticPaths는 production 환경에서 빌드하는 동안에만 실행된다.
즉, 런타임에는 호출되지 않는다.

Where can I use getStaticPaths

• getStaticPaths must be used with getStaticProps
• You cannot use getStaticPaths with getServerSideProps
• You can export getStaticPaths from a Dynamic Route that also uses getStaticProps
• You cannot export getStaticPaths from non-page file (e.g. your components folder)
• You must export getStaticPaths as a standalone function, and not a property of the page component

• getStaticPaths는 반드시 getStaticProps와 함께 사용해야 한다.
• getStaticPaths를 getServerSideProps와 사용할 수 없다.
• getStaticProps를 사용하는 동적 경로에서 getStaticPaths를 export할 수 있다.
• 페이지 파일이 아닌 곳에서 export할 수 없다.
• getStaticPaths는 반드시 독립 실행형 함수여야 한다. page component의 property가 될 수 없다.

Runs on every request in development

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

개발 환경에서 getStaticPaths는 매 요청마다 호출된다.

Generating paths on-demand

getStaticPaths allows you to control which pages are generated during the build instead of on-demand with fallback. Generating more pages during a build will cause slower builds.

getStaticPaths는 fallback을 사용한 on-demand 대신 빌드 중에 생성되는 페이지를 제어할 수 있다.
빌드하는 동안 많은 페이지를 생성하는 것은 빌드를 느리게 한다.

You can defer generating all pages on-demand by returning an empty array for paths. This can be especially helpful when deploying your Next.js application to multiple environments. For example, you can have faster builds by generating all pages on-demand for previews (but not production builds). This is helpful for sites with hundreds/thousands of static pages.

경로에 대한 빈 배열을 반환함으로써 모든 페이지 생성을 지연시킬 수 있다.
이것은 Next.js 어플리케이션을 여러 환경에 배포할 때 특히 유용하다.

예를 들어, 미리보기에 필요한 페이지에 대해 빌드 속도를 높일 수 있다.
이 기능은 수백/수천 개의 정적 페이지를 가지는 사이트일 때 유용하다.

// pages/posts/[id].js

export async function getStaticPaths() {
  // When this is true (in preview environments) don't
  // prerender any static pages
  // (faster builds, but slower initial page load)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Get the paths we want to prerender based on posts
  // In production environments, prerender all pages
  // (slower builds, but faster initial page load)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } means other routes should 404
  return { paths, fallback: false }
}

📎 관련 링크

Next.js 공식문서