Linking and Navigating

Next.js에서 경로를 탐색하는 방법에는 네 가지가 있습니다:

• Link Component
• useRouter hook (Client Components)
• redirect function (Server Components)
• native History API

이 페이지에서는 이러한 각 옵션을 사용하는 방법을 살펴보고 탐색이 작동하는 방식에 대해 자세히 설명합니다.

1. <Link> 컴포넌트

<Link>는 HTML <a> 태그를 확장하여 경로 간 프리페칭 및 클라이언트 측 탐색을 제공하는 기본 제공 컴포넌트입니다. Next.js에서 경로 간을 탐색하는 기본적이고 권장되는 방법입니다.

<Link>를 사용하려면 next/link를 import하고, href props를 컴포넌트에 전달하세요:

1
import Link from 'next/link'
2

3
export default function Page() {
4
  return <Link href="/dashboard">Dashboard</Link>
5
}

<Link>에 전달할 수 있는 선택적 props가 있습니다. 더 많은 정보는 API 레퍼런스를 참고하세요.

1.1 예시

1.1.1 동적 세그먼트에 링크 걸기

동적 세그먼트에 링크를 걸 때, 템플릿 리터럴과 삽입법을 사용하여 링크 목록을 생성할 수 있습니다. 예를 들어, 블로그 포스트 목록을 생성하려면:

1
import Link from 'next/link'
2

3
export default function PostList({ posts }) {
4
  return (
5
    <ul>
6
      {posts.map(post => (
7
        <li key={post.id}>
8
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
9
        </li>
10
      ))}
11
    </ul>
12
  )
13
}

1.1.2 활성 링크 확인하기

링크가 활성화되어 있는지 확인하기 위해 usePathname()을 사용할 수 있습니다. 예를 들어, 현재 pathname이 링크의 href와 일치하는지 확인하여 활성 링크에 클래스를 추가할 수 있습니다:

1
'use client'
2

3
import { usePathname } from 'next/navigation'
4
import Link from 'next/link'
5

6
export function Links() {
7
  const pathname = usePathname()
8

9
  return (
10
    <nav>
11
      <ul>
12
        <li>
13
          <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
14
            Home
15
          </Link>
16
        </li>
17
        <li>
18
          <Link className={`link ${pathname === '/about' ? 'active' : ''}`} href="/about">
19
            About
20
          </Link>
21
        </li>
22
      </ul>
23
    </nav>
24
  )
25
}

1.1.3 id로 스크롤하기

Next.js App 라우터의 기본 동작은 새 경로의 상단으로 스크롤하거나 뒤로 및 앞으로 탐색을 위해 스크롤 위치를 유지하는 것입니다.

경로 탐색에서 특정 ID로 스크롤하려면 URL에 # 해시 링크를 추가하거나 href 프로퍼티에 해시 링크를 전달하면 됩니다. 이는 <Link>가 <a> 요소로 렌더링되므로 가능합니다.

1
<Link href="/dashboard#settings">Settings</Link>
2

3
// Output
4
<a href="/dashboard#settings">Settings</a>

1.1.4 스크롤 복원 비활성화하기

Next.js App 라우터의 기본 동작은 새 경로의 상단으로 스크롤하거나 뒤로 및 앞으로 탐색을 위해 스크롤 위치를 유지하는 것입니다. 이 동작을 비활성화하려면, <Link> 컴포넌트에 scroll={false}를 전달하거나, router.push() 또는 router.replace()에 scroll: false를 전달하면 됩니다.

1
// next/link
2
<Link href="/dashboard" scroll={false}>
3
  Dashboard
4
</Link>

1
// useRouter
2
import { useRouter } from 'next/navigation'
3

4
const router = useRouter()
5

6
router.push('/dashboard', { scroll: false })

2. useRouter() Hook

useRouter hook을 사용하면, 클라이언트 컴포넌트에서 프로그래밍 방식으로 경로를 변경할 수 있습니다.

1
'use client'
2

3
import { useRouter } from 'next/navigation'
4

5
export default function Page() {
6
  const router = useRouter()
7

8
  return (
9
    <button type="button" onClick={() => router.push('/dashboard')}>
10
      Dashboard
11
    </button>
12
  )
13
}

useRouter의 더 많은 정보는 API 레퍼런스를 참고하세요.

추천: useRouter를 사용하라는 특별한 요구사항이 없는 한, 라우트 간에 이동할 때 <Link> 컴포넌트를 사용하는 것이 좋습니다.

3. redirect function

서버 컴포넌트의 경우, redirect 기능을 대신 사용하세요.

1
import { redirect } from 'next/navigation'
2

3
async function fetchTeam(id: string) {
4
  const res = await fetch('https://...')
5
  if (!res.ok) return undefined
6
  return res.json()
7
}
8

9
export default async function Profile({ params }: { params: { id: string } }) {
10
  const team = await fetchTeam(params.id)
11
  if (!team) {
12
    redirect('/login')
13
  }
14

15
  // ...
16
}

알아두면 유용:

• redirect는 기본적으로 307(임시 리디렉션) 상태 코드를 반환합니다.
  • 서버 액션에서 사용하면 303(기타 참조)을 반환하며,
  • 이는 일반적으로 POST 요청의 결과로 성공 페이지로 리디렉션하는 데 사용됩니다.
• redirect는 내부적으로 오류를 발생시키므로 try/catch 블록 외부에서 호출해야 합니다.
• redirect는 렌더링 프로세스 중 클라이언트 컴포넌트에서 호출할 수 있지만 이벤트 핸들러에서는 호출할 수 없습니다.
  • 대신 useRouter 훅을 사용할 수 있습니다.
• redirect는 절대 URL도 허용하며, 외부 링크로 리디렉션하는 데 사용할 수 있습니다.
• 렌더링 프로세스 전에 리디렉션하려면, next.config.js 또는 Middleware를 사용하세요.

자세한 내용은 redirect API 참조를 참조하세요.

4. Using the native History API

Next.js를 사용하면 window.history.pushState 및 window.history.replaceState 메서드를 사용하여 페이지를 다시 로드하지 않고도 브라우저의 기록 스택을 업데이트할 수 있습니다.

pushState 및 replaceState 호출은 Next.js 라우터에 통합되어, usePathname 및 useSearchParams와 동기화할 수 있습니다.

4.1 window.history.pushState

이를 사용하여 브라우저의 history 스택에 새 항목을 추가할 수 있습니다. 사용자는 이전 state로 돌아갈 수 있습니다. 예를 들어, 제품 목록을 정렬할 수 있습니다:

1
'use client'
2

3
import { useSearchParams } from 'next/navigation'
4

5
export default function SortProducts() {
6
  const searchParams = useSearchParams()
7

8
  function updateSorting(sortOrder: string) {
9
    const params = new URLSearchParams(searchParams.toString())
10
    params.set('sort', sortOrder)
11
    window.history.pushState(null, '', `?${params.toString()}`)
12
  }
13

14
  return (
15
    <>
16
      <button onClick={() => updateSorting('asc')}>Sort Ascending</button>
17
      <button onClick={() => updateSorting('desc')}>Sort Descending</button>
18
    </>
19
  )
20
}

4.2 window.history.replaceState

브라우저의 history 스택에서 현재 항목을 바꾸려면 이 기능을 사용합니다. 사용자는 이전 state로 돌아갈 수 없습니다. 예를 들어, 애플리케이션의 locale을 전환할 때 사용합니다:

1
'use client'
2

3
import { usePathname } from 'next/navigation'
4

5
export function LocaleSwitcher() {
6
  const pathname = usePathname()
7

8
  function switchLocale(locale: string) {
9
    // e.g. '/en/about' or '/fr/contact'
10
    const newPath = `/${locale}${pathname}`
11
    window.history.replaceState(null, '', newPath)
12
  }
13

14
  return (
15
    <>
16
      <button onClick={() => switchLocale('en')}>English</button>
17
      <button onClick={() => switchLocale('fr')}>French</button>
18
    </>
19
  )
20
}

5. 내비게이션의 작동 방식

App 라우터는 라우팅과 navigation에 하이브리드 방식을 사용합니다. 서버에서는, 애플리케이션 코드가 경로 세그먼트별로 자동으로 code-split됩니다. 그리고 클라이언트에서는 Next.js가 경로 세그먼트를 prefetches하고 caches합니다. 즉, 사용자가 새 경로로 이동할 때, 브라우저는 페이지를 새로고침하지 않고 변경되는 경로 세그먼트만 다시 렌더링하여 탐색 환경과 성능을 개선합니다.

5.1 코드 분할(code splitting)

코드 분할을 사용하면 애플리케이션 코드를 더 작은 번들로 분할하여 브라우저에서 다운로드하고 실행할 수 있습니다. 이렇게 하면 전송되는 데이터의 양과 각 요청의 실행 시간이 줄어들어 성능이 향상됩니다.

서버 컴포넌트를 사용하면 애플리케이션 코드를 경로 세그먼트별로 자동으로 코드 분할할 수 있습니다. 즉, 현재 경로에 필요한 코드만 내비게이션에 로드됩니다.

5.2 Prefetching

Prefetching은 사용자가 경로를 방문하기 전에 백그라운드에서 경로를 미리 로드하는 방법입니다.

Next.js에서 경로를 프리페칭하는 방법에는 두 가지가 있습니다:

• <Link> component: Routes는 사용자의 뷰포트에 표시될 때 자동으로 Prefetching됩니다.

  • Prefetching은 페이지가 처음 로드될 때 또는 스크롤을 통해 뷰포트에 표시될 때 발생합니다.

• router.prefetch(): useRouter 훅은 프로그래밍 방식으로 경로를 미리 가져오는데 사용할 수 있습니다.

<Link>의 프리페칭 동작은 정적 경로와 동적 경로에 따라 다릅니다:

• 정적 경로(Static Routes): prefetch 기본값은 true입니다. 전체 경로가 prefetched되고 cached됩니다.
• 동적 경로(Dynamic Routes): prefetch 기본값을 자동으로 설정합니다.
  • 렌더링된 컴포넌트의 ‘트리’에서 첫 번째 loading.js 파일까지 공유 레이아웃만 프리페치되고 30초 동안 캐시됩니다.
  • 이렇게 하면 전체 동적 경로를 불러오는 데 드는 비용이 줄어들고,
  • 사용자에게 즉각적인 로딩 상태를 표시하여 더 나은 시각적 피드백을 제공할 수 있습니다.

프리페칭 프로퍼티를 false로 설정하여 prefetch을 비활성화할 수 있습니다.

자세한 내용은 <Link> API 참조를 참조하세요.

알아두면 유용합니다:

Prefetching은 개발 환경에서는 사용할 수 없으며, 프로덕션 환경에서만 사용할 수 있습니다.

5.3 Caching

Next.js에는 라우터 캐시라는 인메모리 클라이언트 측 캐시가 있습니다. 사용자가 앱을 탐색할 때, 미리 가져온 경로 세그먼트와 방문한 경로의 React 서버 컴포넌트 페이로드가 캐시에 저장됩니다.

즉, 탐색 시 서버에 새로 요청하는 대신 캐시를 최대한 재사용합니다.

• 요청 및 데이터 전송 횟수를 줄여 성능을 개선합니다.

즉, 탐색 시 서버에 새로운 요청을 하는 대신 캐시를 최대한 재사용하여 요청과 데이터 전송 횟수를 줄여 성능을 개선합니다.

라우터 캐시의 작동 방식과 구성 방법에 대해 자세히 알아보세요.

5.4 Partial Rendering

부분 렌더링은 내비게이션에서 변경된 경로 세그먼트만 클라이언트에서 다시 렌더링되고 공유 세그먼트는 유지된다는 의미입니다.

예를 들어, 2개의 형제 경로인 /dashboard/settings와 /dashboard/analytics 사이를 탐색하는 경우, settings 및 analytics 페이지가 렌더링되고, 공유 대시보드 레이아웃이 유지됩니다.

부분 렌더링이 없으면, 탐색할 때마다 전체 페이지가 클라이언트에서 다시 렌더링됩니다. 변경되는 세그먼트만 렌더링하면 전송되는 데이터의 양과 실행 시간이 줄어들어 성능이 향상됩니다.

5.5 Soft Navigation

브라우저는 페이지 사이를 이동할 때 “Hard Navigation”을 수행합니다. Next.js 앱 라우터는 페이지 간 “Soft Navigation”을 활성화하여 변경된 경로 세그먼트만 다시 렌더링되도록 합니다(부분 렌더링). 이를 통해 탐색 중에 클라이언트 React 상태를 유지할 수 있습니다.

5.6 Back and Forward Navigation

기본적으로 Next.js는 뒤로 및 앞으로 탐색을 위한 스크롤 위치를 유지하고, 라우터 캐시에서 경로 세그먼트를 재사용합니다.

5.7 page와 app 사이의 라우팅

page/에서 app/으로 점진적으로 마이그레이션할 때 Next.js 라우터는 두 페이지 사이의 하드 네비게이션을 자동으로 처리합니다. pages/에서 app/로의 전환을 감지하기 위해 앱 경로의 확률적 검사를 활용하는 클라이언트 라우터 필터가 있는데, 이 필터는 때때로 오탐을 발생시킬 수 있습니다. 기본적으로 오탐 가능성을 0.01%로 설정하기 때문에 이러한 경우는 매우 드물게 발생합니다. 이 가능성은 next.config.js의 experimental.clientRouterFilterAllowedRate 옵션을 통해 사용자 지정할 수 있습니다. 오탐률을 낮추면 클라이언트 번들에서 생성되는 필터의 크기가 커진다는 점에 유의하세요.

또는 이 처리를 완전히 비활성화하고 page/와 app/ 간의 라우팅을 수동으로 관리하려면, next.config.js에서 experimental.clientRouterFilter를 false로 설정하면 됩니다. 이 기능을 비활성화하면, 앱 경로와 겹치는 페이지의 모든 동적 경로는 기본적으로 제대로 탐색되지 않습니다.