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

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

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

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

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

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

---

Introduction

Next.js has a file-system based router built on the concept of pages.

When a file is added to the pages directory it's automatically available as a route.

The files inside the pages directory can be used to define most common patterns.

Next.js에는 페이지 개념을 기반으로 구축 된 파일 시스템 기반 라우터가 있다. 

파일이 pages 디렉터리에 추가되면 자동으로 경로 접근이 가능해진다.

파일 디렉터리 내부의 파일들을 사용하여 가장 일반적인 패턴을 정의할 수 있다. 

Index routes

The router will automatically route files named index to the root of the directory.
라우터는 index라는 파일을 디렉터리의 루트로 자동 라우팅해준다.

• pages/index.js → /
• pages/blog/index.js → /blog

Nested routes

The router supports nested files. If you create a nested folder structure files will be automatically routed in the same way still. 라우터는 중첩된 파일들에 대해서도 지원한다. 중첩된 폴더 구조를 만들어도 파일들은 같은 방법으로 자동 라우팅 될 것이다.

• pages/blog/first-post.js → /blog/first-post
• pages/dashboard/settings/username.js → /dashboard/settings/username

Dynamic route segments

To match a dynamic segment you can use the bracket syntax. This allows you to match named parameters.
동적인 세그먼트를 일치시키기 위해서 대괄호 구문을 사용할 수 있다. 이렇게 하면 명명된 파라미터들과 일치시킬 수 있다.

• pages/blog/[slug].js → /blog/:slug (/blog/hello-world)
• pages/[username]/settings.js → /:username/settings (/foo/settings)
• pages/post/[...all].js → /post/* (/post/2020/id/title)

Check out the Dynamic Routes documentation to learn more about how they work.
어떻게 동작하는지 확인하려면 Dynamic Routes 문서를 확인하라.

Linking between pages

The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.

A React component called Link is provided to do this client-side route transition.

Next.js 라우터는 페이지 간의 클라이언트 측 경로 전환이 가능하게 해준다. 싱글 페이지 어플리케이션과 비슷하다.

Link라는 리액트 컴포넌트는 이러한 클라이언트 측 경로 전환을 제공해준다.

 

In the example above we have multiple links, each one maps a path (href) to a known page:
위의 예제에서 다수의 링크들이 있고 각 링크는 알려져 있는 페이지로 매핑되어있다.

• / → pages/index.js
• /about → pages/about.js
• /blog/hello-world → pages/blog/[slug].js

Any <Link /> in the viewport (initially or through scroll) will be prefetched by default (including the corresponding data) for pages using Static Generation. The corresponding data for server-rendered routes is not prefetched.

뷰포트(초기이거나 스크롤을 통해서 이거나) 내부에 있는 어떠한 <Link />이든 정적 생성을 사용하여 페이지를 위해 기본적으로 (해당하는 데이터를 포함하여) 먼저 패치될 것이다. 서버 렌더링 경로에 해당하는 데이터는 먼저 패치되지 않는다.

Linking to dynamic paths

You can also use interpolation to create the path, which comes in handy for dynamic route segments. For example, to show a list of posts which have been passed to the component as a prop:

경로를 생성하기 위해서 interpolation(${link}이러한 형태)을 사용할 수 있는데 이렇게 하는 것은 동적 경로 세그먼트들에 유용하다. 예를 들어 컴포넌트에 prop으로 전달되어진 포스트 리스트들을 보여주는 것과 같은 경우.

encodeURIComponent is used in the example to keep the path utf-8 compatible.

이 예제에 사용된 encodeURIComponent는 경로를 utf-8 호환가능하게 유지해준다.

Alternatively, using a URL Object:

그렇지 않으면 URL 객체를 사용할 수도 있다.

Now, instead of using interpolation to create the path, we use a URL object in href where:

• pathname is the name of the page in the pages directory. /blog/[slug] in this case.
• query is an object with the dynamic segment. slug in this case.

경로를 만들기 위해서 interpolation을 사용하는 대신 href에 URL 객체를 사용하였다.

• pathname은 pages 디렉터리에 있는 페이지의 이름이다. 이 경우에는 /blog/[slug]이다.
• query는 동적 세그먼트가 있는 객체이다. 이 경우에는 slug이다.

Injecting the router

To access the [router object](https://nextjs.org/docs/api-reference/next/router#router-object) in a React component you can use [useRouter](<https://nextjs.org/docs/api-reference/next/router#userouter>) or [withRouter](<https://nextjs.org/docs/api-reference/next/router#withrouter>).

In general we recommend using [useRouter](<https://nextjs.org/docs/api-reference/next/router#userouter>).

리액트 컴포넌트의 router 객체에 접근하기 하려면 useRouter 혹은 withRouter를 사용할 수 있다.

보통은 useRouter를 사용하는 것을 추천한다.

Dynamic Routes

Defining routes by using predefined paths is not always enough for complex applications. In Next.js you can add brackets to a page ([param]) to create a dynamic route (a.k.a. url slugs, pretty urls, and others).

먼저 정의된 경로만 사용해서 라우트를 정의하는 것은 복잡한 어플리케이션에도 항상 충분한 것은 아니다. Next.js에서는 동적 라우트를 생성하려면 페이지에 대괄호를 더해주면 된다.

Consider the following page pages/post/[pid].js:

아래의 pages/post/[pid].js라는 페이지를 살펴보자:

Any route like /post/1, /post/abc, etc. will be matched by pages/post/[pid].js. The matched path parameter will be sent as a query parameter to the page, and it will be merged with the other query parameters.

/post/1, /post/abc와 같은 어떤 라우트로 pages/post/[pid].js와 매치될 것이다. 매치된 경로 파라미터는 쿼리 파라미터로 페이지에 전송될 것이고 다른 쿼리 파라미터와 함께 합쳐질 것이다.

For example, the route /post/abc will have the following query object:

예를 들어 /post/abc/ 라우트는 아래와 같은 쿼리 객체를 갖는다:

Similarly, the route /post/abc?foo=bar will have the following query object:

비슷하게 /post/abc?foo=bar 라우트는 아래와 같은 쿼리 객체를 갖는다:

However, route parameters will override query parameters with the same name. For example, the route /post/abc?pid=123 will have the following query object:

하지만 같은 이름을 가진 쿼리 파라미터는 라우트 파라미터가 덮어쓸 것이다. 예를 들면 /post/abc/abc?pid=123라는 라우트는 아래와 같은 쿼리 객체를 갖는다.

Multiple dynamic route segments work the same way. The page pages/post/[pid]/[comment].js will match the route /post/abc/a-comment and its query object will be:

다중 동적 라우트 세그먼트도 같은 방법으로 동작한다. pages/post/[pid]/[comment].js 페이지는 /post/abc/a-comment와 매치될 것이고 쿼리 객체는 아래와 같다:

Client-side navigations to dynamic routes are handled with next/link. If we wanted to have links to the routes used above it will look like this:

동적 경로에 대한 클라이언트 측 네비게이션은 next/link로 처리된다. 위에 나온 경로들에 대한 링크들을 원할 때 아래와 같이 보여질 것이다:

Read our docs for Linking between pages to learn more.

더 알아보려면 Linking between pages를 위한 페이지를 읽어보라.

Catch all routes

Dynamic routes can be extended to catch all paths by adding three dots (...) inside the brackets. For example:

• pages/post/[...slug].js matches /post/a, but also /post/a/b, /post/a/b/c and so on.

동적 경로는 점 3개를 (...) 대괄호 안에 추가하여 모든 경로를 다 포함하도록 확장될 수 있다. 예를 들면:

• pages/post/[...slug].js 는  /post/a 에 매칭되지만,  /post/a/b, /post/a/b/c 도 모두 매칭된다.

Note: You can use names other than slug, such as: [...param]

노트: slug말고도 [...param]과 같은 다른 이름을 사용할 수도 있다.

 

Matched parameters will be sent as a query parameter (slug in the example) to the page, and it will always be an array, so, the path /post/a will have the following query object:

매치되는 파라미터들은 쿼리 파라미터로 페이지로 보내질 것이다. (예시에 나오는 slug) 파라미터는 항상 배열이다. /post/a 는 아래와 같은 쿼리 객체를 갖는다.

And in the case of /post/a/b, and any other matching path, new parameters will be added to the array, like so:

그리고 /post/a/b의 경우에는 또 다른 매치되는 경로로 새로운 파라미터는 배열에 이처럼 추가될 것이다.:

Optional catch all routes

Catch all routes can be made optional by including the parameter in double brackets ([[...slug]]).

For example, pages/post/[[...slug]].js will match /post, /post/a, /post/a/b, and so on.

The main difference between catch all and optional catch all routes is that with optional, the route without the parameter is also matched (/post in the example above).

The query objects are as follows:

이중 괄호 안에 파라미터를 포함하여 모든 라우트를 선택적으로 포함할 수 있다.

예를 들면 pages/post/[[...slug]].js 는 /post, /post/a, /post/a/b 모두 매치될 것이다.

모든 경로를 포함하는 것과 선택적으로 모든 경로를 포함하는 것의 주된 차이점은 파라미터가 없는 경로도 매치가 된다는 것이다. (위의 예시에 나오는 /post와 같은 것)

쿼리 객체는 아래와 같다:

Caveats

• Predefined routes take precedence over dynamic routes, and dynamic routes over catch all routes. Take a look at the following examples:
  사전 정의된 경로는 동적 경로보다 우위이며 동적 경로는 모든 경로를 포착하는 것보다 우위이다. 아래의 예시들을 보라:
  • pages/post/create.js - Will match /post/create
  • pages/post/[pid].js - Will match /post/1, /post/abc, etc. But not /post/create
  • pages/post/[...slug].js - Will match /post/1/2, /post/a/b/c, etc. But not /post/create, /post/abc
• Pages that are statically optimized by Automatic Static Optimization will be hydrated without their route parameters provided, i.e query will be an empty object ({}).
  Automatic Static Optimization에 의해 정적으로 최적화된 페이지는 제공된 경로 파라미터없이 hydrate될 것이다. query는 빈 객체일 것이다.
• After hydration, Next.js will trigger an update to your application to provide the route parameters in the query object.
  hydration* 후에 Next.js는 어플리케이션 업데이터를 트리거하여 쿼리 객체에 경로 파라미터를 제공한다.*Hydration: 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 페이지 (페이지에 필요한 최소한의 자바스크립트 코드와 연결되어 있는)가 브라우저에 로드되면 자바스크립트 코드가 실행되고 페이지가 완전히 인터랙티브하게 되는 과정.

Imperatively

next/link should be able to cover most of your routing needs, but you can also do client-side navigations without it, take a look at the documentation for next/router.

The following example shows how to do basic page navigations with useRouter:

next/link가 routing에 필요한 거의 대부분의 것을 커버할 수 있어야 하지만 next/link 없이 클라이언트 측에서 이동하는 것도 가능하다. next/router 문서를 참조하라.

아래의 예제는 useRouter로 어떻게 기본적인 페이지 네비게이션이 가능한지 보여준다.

Shallow Routing

Shallow routing allows you to change the URL without running data fetching methods again, that includes [getServerSideProps](<https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering>), [getStaticProps](<https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation>), and [getInitialProps](<https://nextjs.org/docs/api-reference/data-fetching/getInitialProps>).

You'll receive the updated pathname and the query via the [router object](https://nextjs.org/docs/api-reference/next/router#router-object) (added by [useRouter](<https://nextjs.org/docs/api-reference/next/router#userouter>) or [withRouter](<https://nextjs.org/docs/api-reference/next/router#withrouter>)), without losing state.

To enable shallow routing, set the shallow option to true. Consider the following example:

Shallow routing은 getServerSideProps, getStaticProps, getInitalProps 같은 데이터를 가져오는 메소드를 다시 동작시키지 않고도 URL 변경을 가능하게 해준다.

업데이트된 pathname과 query를 상태를 잃지않고 router 객체를 통해서(useRouter나 withRouter에 의해 추가된) 받을 것이다.

Shallow routing을 사용하려면 shallow 옵션을 true로 주어야한다. 아래의 예제를 고려해보라:

The URL will get updated to /?counter=10. and the page won't get replaced, only the state of the route is changed.

You can also watch for URL changes via componentDidUpdate as shown below:

URL은 conter=10으로 업데이트 될 것이다. 페이지는 대체되지 않을 것이고 라우트의 상태만 변경될 것이다.

아래와 같이 URL이 변경되는 것을 componentDidUpdate를 통해서도 확인할 수 있다

Caveats

Shallow routing only works for same page URL changes. For example, let's assume we have another page called pages/about.js, and you run this:

Shallow routing은 동일한 페이지의 URL 변경에 대해서만 동작한다. 예를 들어 pages/about.js 라는 다른 페이지가 있다고 하고 이것을 실행하면:

Since that's a new page, it'll unload the current page, load the new one and wait for data fetching even though we asked to do shallow routing.

이것은 새로운 페이지이기 때문에 현재 페이지는 언로드되고 새로운 페이지가 로드되고 shallow routing을 요청하긴 했지만 데이터가 패치되는 것을 기다릴 것이다.