[내보내번] Next.js docs - Pages

내보내번(내가 보려고 내가 번역한...) Next.js docs

2021년 3월 26일 기준 Next.js 공식 문서를 번역했다.

※ 영어 전공자도 해외 유학파도 아니기에 번역에는 의역, 오역이 무수히 많을 수 있으며, 혼자 공식문서를 참조해가며 번역하다 보니 오타도 많을 수 있다. 정확한 내용은 공식문서를 직접 살펴보거나 다른 정보들을 더 찾아보는 것을 추천한다.

(하지만 댓글 피드백도 환영합니다😃 )

Next.js 공식문서 확인하기>>

Pages

In Next.js, a page is a React Component exported from a .js, .jsx, .ts, or .tsx file in the pages directory. Each page is associated with a route based on its file name.

Next.js에서 페이지는 pages 디렉토리 안에 있는 .js, .jsx, .ts, or .tsx 파일에 있는 export된 React 컴포넌트이다. 각 페이지는 파일의 이름에 따른 route로 연결된다.

Example: If you create pages/about.js that exports a React component like below, it will be accessible at /about.

예시: 아래와 같은 React 컴포넌트를 export하는 pages/about.js를 생성하면 /about에서 접근이 가능할 것이다.

function About() {
  return <div>About</div>}

export default About

pages with Dynamic Routes 동적 경로와 페이지

Next.js supports pages with dynamic routes. For example, if you create a file called pages/posts/[id].js, then it will be accessible at posts/1, posts/2, etc.

Next.js는 다이나믹(동적) 라우트를 지원한다. 예를 들어 pages/posts/[id].js란 파일을 생성하면 post/1, post/2 같은 경로로 접근이 가능하다.

Dynamic Routing documentation 참조

Pre-rendering 사전 렌더링

By default, Next.js pre-renders every page. This means that Next.js generates HTML for each page in advance, instead of having it all done by client-side JavaScript. Pre-rendering can result in better performance and SEO.

기본적으로 Next.js는 모든 페이지를 먼저 렌더링한다. 먼저 렌더링 한다는 것은 Next.js가 클라이언트 사이드의 JavasScript에 의해 렌더링 되기 전에 각 페이지의 HTML을 먼저 생성한다는 의미이다. Pre-rendering(사전 렌더링)은 더 나은 성능과 SEO(Search Engine Optimization)를 가져올 수 있다.

Each generated HTML is associated with minimal JavaScript code necessary for that page. When a page is loaded by the browser, its JavaScript code runs and makes the page fully interactive. (This process is called hydration.)

생성된 각 HTML은 각 페이지에 필요한 최소한의 JS코드와 연결된다. 페이지가 브라우저에 의해서 로드되면 페이지의 스크립트 코드가 동작하면서 그 페이지가 인터랙티브 하게 만들어준다. (이 과정을 하이드레이션이라고 부름)

Two forms of Pre-rendering 두 가지 형태의 사전 렌더링

Next.js has two forms of pre-rendering: Static Generation and Server-side Rendering. The difference is in when it generates the HTML for a page.

Next.js는 사전 렌더링의 두가지 형태가 있다: 정적 생성, 서버 사이드 렌더링. 차이점은 언제 페이지를 위한 HTML를 생성하는가에 있다.

• Static Generation (Recommended): The HTML is generated at build time and will be reused on each request.
  정적 생성(추천): 빌드 시간에 HTML이 생성되고 각 요청마다 재사용이 된다.
• Server-side Rendering: The HTML is generated on each request.
  서버 사이드 렌더링: 각 요청마다 HTML이 생성된다.

Importantly, Next.js lets you choose which pre-rendering form you'd like to use for each page. You can create a "hybrid" Next.js app by using Static Generation for most pages and using Server-side Rendering for others.
중요하게도 Next.js는 각 페이지마다 당신이 원하는 사전 렌더링 형태를 선택할 수 있게 되어 있다. 대부분의 페이지를 정적인 생성을 사용하고 나머지에 서버 사이드 렌더링을 사용하는 하이브리드 Next.js 앱을 생성할 수도 있다.

We recommend using Static Generation over Server-side Rendering for performance reasons. Statically generated pages can be cached by CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option.

우리는 성능상의 이유로 서버 사이드 렌더링보다는 정적 생성을 사용하기를 추천한다. 정적으로 생성되는 페이지는 성능을 높이기 위해서 추가적인 설정 없이도 CDN에 의해서 캐싱된다. 하지만 어떤 경우에는 서버 사이드 렌더링을 사용할 수밖에 없을 수도 있다.

You can also use Client-side Rendering along with Static Generation or Server-side Rendering. That means some parts of a page can be rendered entirely by client side JavaScript. To learn more, take a look at the Data Fetching documentation.

클라이언트 사이드 렌더링도 정적 생성이나 서버 사이드 렌더링과 함께 사용할 수 있다. 이 말의 의미는 페이지의 어떤 부분은 클라이언트 사이드 자바스크립트에 의해서만 렌더할 수도 있다.

Static Generation(Recommended) 정적 생성(추천)

If a page uses Static Generation, the page HTML is generated at build time. That means in production, the page HTML is generated when you run next build . This HTML will then be reused on each request. It can be cached by a CDN.

페이지가 정적 생성을 사용한다면 해당 페이지의 HTML은 빌드 타임에 생성된다. 이 말의 의미는 운영 시에(?) 해당 페이지의 HTML는 next build를 동작시킬 때에 생성된다. 이 HTML은 매 요청마다 재 사용될 것이다. 이것은 CDN에 의해서 캐싱된다.

In Next.js, you can statically generate pages with or without data. Let's take a look at each case.

Next.js에서 개발자는 페이지를 데이터를 포함할 수도, 포함하지 않을 수도 있다. 각 케이스에 대해 살펴보자.

Static Generation without data 데이터 없이 정적 생성하기

By default, Next.js pre-renders pages using Static Generation without fetching data. Here's an example:

기본적으로 Next.js는 데이터를 가지고 오지 않는 정적 생성으로 페이지를 사전 렌더링 한다.

Note that this page does not need to fetch any external data to be pre-rendered. In cases like this, Next.js generates a single HTML file per page during build time.

이 페이지는 어떠한 외부의 데이터로 가져올 필요가 없이 사전 렌더링이 되는 것을 유의하였을 것이다. 이러한 경우에는 Next.js는 빌드 시간에 페이지 당 한 개의 HTML 파일을 생성한다.

scenario 1: Your page content depends on external data 페이지 콘텐츠가 외부 데이터에 의존해있음

Example: Your blog page might need to fetch the list of blog posts from a CMS (content management system).

예시: 당신의 블로그 페이지가 CMS로부터 블로그 포스트의 리스트를 가져올 필요가 있는 경우.

// TODO: Need to fetch `posts` (by calling some API endpoint)
//       before this page can be pre-rendered.
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>))}
    </ul>)
}

export default Blog

To fetch this data on pre-render, Next.js allows you to export an async function called getStaticProps from the same file. This function gets called at build time and lets you pass fetched data to the page's props on pre-render.

사전 렌더 시에 이 데이터를 가져오기 위해 Next.js는 당신이 동일한 파일 내에 getStaticProps라는 async(비동기) 함수를 export하는 것을 허용한다. 이 함수는 빌드 시간에 호출되어 불러온 데이터를 사전 렌더시에 페이지의 props으로 전달한다.

function Blog({ posts }) {
  // Render posts...
}

// This function gets called at build time
export async function getStaticProps() {
  // Call an external API endpoint to get posts
  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

To learn more about how getStaticProps works, check out the Data Fetching documentation.

getStaticProps가 어떻게 동작하는지 더 알아보기 위해선 Data Fetching 문서를 확인하라.

Scenario 2: Your page paths depend on external data 페이지 경로가 외부 데이터에 의존해있음

Next.js allows you to create pages with dynamic routes. For example, you can create a file called pages/posts/[id].js to show a single blog post based on id. This will allow you to show a blog post with id: 1 when you access posts/1.

Next.js는 당신이 페이지를 동적인 라우트로 생성할 수 있게 허용한다. 예를 들어 한 개의 블로그 포스트를 id기반으로 보여주기 위해서 pages/posts/[id].js라는 파일을 생성할 수 있다. 이렇게 하면 id가 1인 블로그 포스트를 posts/1로 접근하여 볼 수 있게 해준다.

However, which id you want to pre-render at build time might depend on external data.

그러나 어떤 id를 빌드 시간에 사전 렌더하고 싶은지는 외부 데이터에 달려있다(?)

Example: suppose that you've only added one blog post (with id: 1) to the database. In this case, you'd only want to pre-render posts/1 at build time.

예시: 당신이 id가 1인 블로그 포스트를 데이터 베이스에 추가했다. 이 경우에 당신은 빌드 시간에 posts/1만 사전 렌더 하고 싶을 것이다.

Later, you might add the second post with id: 2. Then you'd want to pre-render posts/2 as well.

그 후에 id가 2인 두 번째 포스트를 추가했다. 그럼 posts/2도 사전 랜더하고 싶을 것이다.

So your page paths that are pre-rendered depend on external data. To handle this, Next.js lets you export an async function called getStaticPaths from a dynamic page (pages/posts/[id].js in this case). This function gets called at build time and lets you specify which paths you want to pre-render.

그렇기 때문에 당신의 사전 렌더된 페이지 경로는 외부 데이터에 달려있다. 이것을 핸들링 하기 위해서 Next.js는 동적인 페이지를 위해서 getStaticPaths라는 비동기 함수를 동적인 페이지에서 export할 수 있게 한다. 이 함수는 빌드 시간에 호출되고 어떤 경로들을 사전 렌더하기 원하는지 특정 지을 수 있다.

// This function gets called at build time
export async function getStaticPaths() {
  // 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 pre-render based on posts
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // We'll pre-render only these paths at build time.
  // { fallback: false } means other routes should 404.
  return { paths, fallback: false }
}

Also in pages/posts/[id].js, you need to export getStaticProps so that you can fetch the data about the post with this id and use it to pre-render the page:

또한 pages/posts/[id].js파일에서 포스트에 대한 데이터를 해당 id로 가져오고 사전 렌더에 사용하기 위해서는 getStaticProps 함수를 export해야한다.

*fallback: false라는 옵션은 허용된 경로 외에 다른 경로는 404를 던지는 것.

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

export async function getStaticPaths() {
  // ...
}

// This also gets called at build time
export async function getStaticProps({ params }) {
  // params contains the post `id`.
  // If the route is like /posts/1, then params.id is 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Pass post data to the page via props
  return { props: { post } }
}

export default Post

To learn more about how getStaticPaths works, check out the Data Fetching documentation.

getStaticPaths가 어떻게 동작하는지 더 자세한 내용은 Data Fetching 문서 참조

When should I use Static Generation? 언제 정적 생성을 사용해야할까?

We recommend using Static Generation (with and without data) whenever possible because your page can be built once and served by CDN, which makes it much faster than having a server render the page on every request.

데이터를 포함하던 그렇지 않던 가능한한 정적 생성을 사용하기를 추천한다. 당신의 페이지들이 한번에 생성되고 CDN에 의해 제공되기 때문에 페이지들이 요청 때마다 서버에서 렌더하는 것보다 훨씬 더 빠르다.

You can use Static Generation for many types of pages, including:

• Marketing pages
• Blog posts
• E-commerce product listings
• Help and documentation

You should ask yourself: "Can I pre-render this page ahead of a user's request?" If the answer is yes, then you should choose Static Generation.

"사용자가 요청하기 전에 이 페이지를 사전 렌더해도 되는가"하고 먼저 물어 볼 수 있다. 만약 그렇다면 정적인 생성을 선택하는 것이 좋다.

On the other hand, Static Generation is not a good idea if you cannot pre-render a page ahead of a user's request. Maybe your page shows frequently updated data, and the page content changes on every request.

반면에 사용자의 요청 전에 페이지를 사전 렌더할 수 없다면 정적 생성은 좋은 아이디어가 아니다. 아마도 자주 업데이트되는 데이터를 보여주는 페이지 이거나 매 요청 마다 변경되는 경우라면...

In cases like this, you can do one of the following:

• Use Static Generation with Client-side Rendering: You can skip pre-rendering some parts of a page and then use client-side JavaScript to populate them. To learn more about this approach, check out the Data Fetching documentation.
• Use Server-Side Rendering: Next.js pre-renders a page on each request. It will be slower because the page cannot be cached by a CDN, but the pre-rendered page will always be up-to-date. We'll talk about this approach below.

이런 경우라면 다음의 내용 중 하나를 시도해볼 수 있다.

• 정적 생성을 클라이언트 사이드 렌더링과 함께 사용하기: 페이지의 어떤 부분을 사전 렌더링하는 과정을 생략하고 클라이언트 사이드 자바스크립트로 데이터를 추가할 수 있다. 이 방식에 대해서 더 알기 원한다면 Data Fetching 문서를 참고하라.
• 서버 사이드 렌더링 사용하기: Next.js는 페이지 요청마다 사전 렌더한다. 이 방식은 CDN에 의해 캐싱이 되지 않기 때문에 더 느릴 수 있다. 그렇지만 사전 렌더된 페이지는 항상 최신의 상태일 것이다. 이 방식에 대해서는 아래에서 살펴볼 것이다.

Server-side Rendering (SSR, Dynamic Rendering) 서버 사이드 렌더링

If a page uses Server-side Rendering, the page HTML is generated on each request.

페이지가 서버 사이드 렌더링을 사용한다면 HTML페이지는 요청때마다 생성될 것이다.

To use Server-side Rendering for a page, you need to export an async function called getServerSideProps. This function will be called by the server on every request.

페이지에 서버 사이드 렌더링을 사용하기 위해서는 getServerSideProps라는 비동기 함수를 export해야한다. 이 함수는 서버에 의해서 매 요청 마다 호출될 것이다.

For example, suppose that your page needs to pre-render frequently updated data (fetched from an external API). You can write getServerSideProps which fetches this data and passes it to Page like below:

예를 들어 가령 당신의 페이지가 자주 업데이트 되는 데이터(외부 API에서 가져오는)에 의해 사전 렌더될 필요가 있다면 이 데이터들을 가져와서 전달하기 위해 getServerSideProps를 아래와 같이 사용할 수 있다.

function Page({ data }) {
  // Render data...
}

// This gets called on every request
export async function getServerSideProps() {
  // Fetch data from external API
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // Pass data to the page via props
  return { props: { data } }
}

export default Page

As you can see, getServerSideProps is similar to getStaticProps, but the difference is that getServerSideProps is run on every request instead of on build time.

코드에서 볼 수 있듯이 getServerSideProp는 getStaticProps와 비슷하지만 차이점이라면 getServerSideProps는 빌드 시간때만이 아니라 매 요청마다 호출된다는 것이다.

To learn more about how getServerSideProps works, check out our Data Fetching documentation

getServerSideProps이 어떻게 동작하는지는 Data Fetching 문서 참조

Summary 요약

We've discussed two forms of pre-rendering for Next.js.

• Static Generation (Recommended): The HTML is generated at build time and will be reused on each request. To make a page use Static Generation, either export the page component, or export getStaticProps (and getStaticPaths if necessary). It's great for pages that can be pre-rendered ahead of a user's request. You can also use it with Client-side Rendering to bring in additional data.
• Server-side Rendering: The HTML is generated on each request. To make a page use Server-side Rendering, export getServerSideProps. Because Server-side Rendering results in slower performance than Static Generation, use this only if absolutely necessary.
• 정적 생성(추천): HTML이 빌드 시간에 생성되고 매 요청마다 재사용된다. 페이지를 정적 생성을 사용하여 만드려면 페이지 컴포넌트를 export하거나 getStaticProps를 (그리고 필요하다면 getStaticPaths도) export한다. 사용자의 요청 전에 사전 렌더되어도 되는 페이지들에 좋다. 정적 생성을 추가적인 데이터를 가져오기 위해 클라이언트 사이트 렌더링과 같이 사용할 수도 있다.
• 서버 사이드 렌더링: HTML이 매 요청마다 생성된다. 페이지에서 서버 사이드 렌더링을 하려면 getServerSideProps export한다. 서버 사이드 렌더링은 정적 생성보다 더 낮은 성능을 보이기 때문에 반드시 필요한 경우에만 사용하라.