Parallel Routes

병렬 경로(Parallel Routes)를 사용하면 동일한 레이아웃 내에서 하나 이상의 페이지를 동시에 또는 조건부로 렌더링할 수 있습니다. 대시보드나 소셜 사이트의 피드와 같이 앱의 매우 동적인 섹션에 유용합니다.

예를 들어, 대시보드를 고려할 때, 병렬 경로를 사용하여 team 페이지와 analytics 페이지를 동시에 렌더링할 수 있습니다:

1. Slots(슬롯; 자리)

병렬 경로는 명명된 Slots을 사용하여 만들어집니다. Slots은 @folder 규칙으로 정의됩니다. 예를 들어, 다음 파일 구조는 두 개의 Slots을 정의합니다: @analytics과 @team:

Slots은 공유 부모 레이아웃에 props으로 전달됩니다. 위의 예제에서, app/layout.js의 컴포넌트는 이제 @analytics 및 @team 슬롯 props을 허용하며, 하위 props과 함께 병렬로 렌더링할 수 있습니다:

1
export default function Layout({
2
  children,
3
  team,
4
  analytics,
5
}: {
6
  children: React.ReactNode
7
  analytics: React.ReactNode
8
  team: React.ReactNode
9
}) {
10
  return (
11
    <>
12
      {children}
13
      {team}
14
      {analytics}
15
    </>
16
  )
17
}

그러나 Slots은 경로 세그먼트가 아니며 URL 구조에 영향을 미치지 않습니다. 예를 들어, /dashboard/@analytics/views의 경우, @analytics가 Slots이므로 URL은 /dashboard/views가 됩니다.

알아두면 유용합니다:

자식 프로퍼티는 폴더에 매핑할 필요가 없는 암시적 Slots입니다. 즉, app/page.js는 app/@children/page.js와 동일합니다.

2. Active state and navigation

기본적으로, Next.js는 각 slot의 활성 상태(또는 하위 페이지)를 추적합니다. 그러나, 슬롯 내에서 렌더링되는 콘텐츠는 탐색 유형에 따라 달라집니다:

• 소프트 탐색(soft navigation):
  • 클라이언트 측 탐색 중에 Next.js는 부분 렌더링을 수행하여 슬롯 내의 하위 페이지를 변경하는 동시에,
  • 다른 슬롯의 활성 하위 페이지는 현재 URL과 일치하지 않더라도 유지합니다.
• 하드 탐색(hard navigation):
  • 전체 페이지 로드(브라우저 새로 고침) 후 Next.js는 현재 URL과 일치하지 않는 슬롯의 활성 상태를 확인할 수 없습니다.
  • 대신 일치하지 않는 슬롯에 대해 default.js 파일을 렌더링하거나, default.js가 존재하지 않는 경우, 404를 렌더링합니다.

알아두면 유용합니다:

일치하지 않는 경로에 대한 404는 의도하지 않은 페이지에 실수로 병렬 경로가 렌더링되는 것을 방지하는 데 도움이 됩니다.

2.1 default.js

초기 로드 또는 전체 페이지 다시 로드 중에 일치하지 않는 slot에 대한 폴백으로 렌더링할 default.js 파일을 정의할 수 있습니다.

다음 폴더 구조를 고려하세요. @team 슬롯에는 /settings 페이지가 있지만, @analytics에는 설정 페이지가 없습니다.

/dashboard/settings으로 이동할 때, @team slot은 @analytics slot의 현재 활성 페이지를 유지하면서, /settings 페이지를 렌더링합니다.

새로 고침 시, Next.js는 @analytics에 대한 default.js를 렌더링합니다. default.js가 존재하지 않으면 404가 대신 렌더링됩니다.

또한 children는 암시적 slot이므로, Next.js가 상위 페이지의 활성 상태를 복구할 수 없는 경우, 하위 페이지에 대한 폴백을 렌더링하는 default.js 파일도 만들어야 합니다.

2.2 useSelectedLayoutSegment(s)

useSelectedLayoutSegment 와 useSelectedLayoutSegments 는 모두 슬롯 내에서 활성 경로 세그먼트를 읽을 수 있는 parallelRoutesKey 매개변수를 허용합니다.

1
'use client'
2

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

5
export default function Layout({ auth }: { auth: React.ReactNode }) {
6
  const loginSegments = useSelectedLayoutSegment('auth')
7
  // ...
8
}

사용자가 app/@auth/login(또는 URL 표시줄의 /login)으로 이동하면 loginSegments는 "login" 문자열과 동일합니다.

3. 예시

3.1 Conditional(조건부) Routes

병렬 경로를 사용하여 사용자 역할과 같은 특정 조건에 따라 조건부로 경로를 렌더링할 수 있습니다. 예를 들어, /admin 또는 /user 역할에 대해 다른 대시보드 페이지를 렌더링할 수 있습니다:

1
import { checkUserRole } from '@/lib/auth'
2

3
export default function Layout({ user, admin }: { user: React.ReactNode; admin: React.ReactNode }) {
4
  const role = checkUserRole()
5
  return <>{role === 'admin' ? admin : user}</>
6
}

3.2 Tab Groups

슬롯 안에 layout을 추가하여, 사용자가 슬롯을 독립적으로 탐색할 수 있도록 할 수 있습니다. 이 기능은 탭을 만들 때 유용합니다.

예를 들어, @analytics 슬롯에는 두 개의 하위 페이지가 있습니다: /page-views 및 /visitors.

@analytics 내에서, layout 파일을 만들어 두 페이지 간에 탭을 공유합니다:

1
import Link from 'next/link'
2

3
export default function Layout({ children }: { children: React.ReactNode }) {
4
  return (
5
    <>
6
      <nav>
7
        <Link href="/dashboard/page-views">Page Views</Link>
8
        <Link href="/dashboard/visitors">Visitors</Link>
9
      </nav>
10
      <div>{children}</div>
11
    </>
12
  )
13
}

3.3 Modal

병렬 경로를 인터셉팅 경로와 함께 사용하여 모달을 만들 수 있습니다. 이를 통해 모달을 만들 때 다음과 같은 일반적인 문제를 해결할 수 있습니다:

• URL을 통해 모달 콘텐츠를 공유할 수 있도록 설정합니다.
• 페이지를 새로 고칠 때 모달을 닫는 대신 컨텍스트를 유지합니다.
• 이전 경로로 이동하지 않고 뒤로 탐색할 때 모달을 닫습니다.
• 앞으로 탐색에서 모달을 다시 엽니다.

사용자가 클라이언트 측 탐색을 사용하여 레이아웃에서 로그인 모달을 열거나 별도의 /login 페이지에 액세스할 수 있는, 다음 UI 패턴을 고려하세요:

이 패턴을 구현하려면, 먼저 기본 로그인 페이지를 렌더링하는 /login 경로를 생성합니다.

1
import { Login } from '@/app/ui/login'
2

3
export default function Page() {
4
  return <Login />
5
}

그런 다음 @auth 슬롯에, null을 반환하는 default.js 파일을 추가합니다. 이렇게 하면 모달이 활성화되어 있지 않을 때 렌더링되지 않습니다.

1
export default function Default() {
2
  return null
3
}

@auth 슬롯 내에서 /(.)login 폴더를 업데이트하여 /login 경로를 가로채세요. <Modal> 컴포넌트와 그 하위 컴포넌트를 /(.)login/page.tsx 파일로 가져옵니다:

1
import { Modal } from '@/app/ui/modal'
2
import { Login } from '@/app/ui/login'
3

4
export default function Page() {
5
  return (
6
    <Modal>
7
      <Login />
8
    </Modal>
9
  )
10
}

알아두면 유용합니다:

• 경로를 가로채는 데 사용되는 규칙(e.g.: (.))은 파일 시스템 구조에 따라 다릅니다. 경로 인터셉트 규칙을 참조하십시오.
• <Modal> 기능을 모달 콘텐츠(<Login>)와 분리하면 모달 내부의 모든 콘텐츠(예: forms)가 서버 컴포넌트인지 확인할 수 있습니다.
  • 자세한 내용은 클라이언트 및 서버 컴포넌트 인터리빙을 참조하세요.

3.3.1 모달 열기

이제 Next.js 라우터를 활용하여 모달을 열고 닫을 수 있습니다. 이렇게 하면 모달이 열려 있을 때와 앞뒤로 탐색할 때 URL이 올바르게 업데이트됩니다.

모달을 열려면, @auth 슬롯을 부모 레이아웃에 프로퍼티로 전달하고, children 프로퍼티와 함께 렌더링합니다.

1
import Link from 'next/link'
2

3
export default function Layout({ auth, children }: { auth: React.ReactNode; children: React.ReactNode }) {
4
  return (
5
    <>
6
      <nav>
7
        <Link href="/login">Open modal</Link>
8
      </nav>
9
      <div>{auth}</div>
10
      <div>{children}</div>
11
    </>
12
  )
13
}

사용자가 <Link>를 클릭하면, /login 페이지로 이동하는 대신 모달이 열립니다. 그러나, 새로 고침 또는 최초 로드 시에는 /login으로 이동하면, 기본 로그인 페이지로 이동합니다.

3.3.2 모달 닫기

router.back()을 호출하거나, Link 컴포넌트를 사용하여 모달을 닫을 수 있습니다.

1
'use client'
2

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

5
export function Modal({ children }: { children: React.ReactNode }) {
6
  const router = useRouter()
7

8
  return (
9
    <>
10
      <button
11
        onClick={() => {
12
          router.back()
13
        }}
14
      >
15
        Close modal
16
      </button>
17
      <div>{children}</div>
18
    </>
19
  )
20
}

Link 컴포넌트를 사용하여 더 이상 @auth 슬롯을 렌더링해서는 안 되는 페이지에서 다른 페이지로 이동하는 경우, null를 반환하는 catch-all 경로를 사용합니다.

1
import Link from 'next/link'
2

3
export function Modal({ children }: { children: React.ReactNode }) {
4
  return (
5
    <>
6
      <Link href="/">Close modal</Link>
7
      <div>{children}</div>
8
    </>
9
  )
10
}

1
export default function CatchAll() {
2
  return null
3
}

알아두면 유용합니다:

• 활성 상태 및 탐색에 설명된 동작 때문에 모달을 닫을 때, @auth 슬롯에 포괄적인 경로를 사용합니다.
  • 더 이상 슬롯과 일치하지 않는 경로에 대한 클라이언트 측 탐색이 계속 표시되므로,
  • 모달을 닫으려면 슬롯을 null을 반환하는 경로에 일치시켜야 합니다.
• 다른 예로는 갤러리에서 사진 모달을 열면서 전용 /photo/[id] 페이지도 함께 열거나, 사이드 모달에서 쇼핑 카트를 여는 것 등이 있습니다.
• 가로채기 및 병렬 경로가 있는 모달의 예시를 확인하세요.

3.4 로딩 및 오류 UI

병렬 경로(Parallel Routes)를 독립적으로 스트리밍할 수 있으므로, 각 경로에 대해 독립적인 오류 및 로딩 상태를 정의할 수 있습니다:

자세한 내용은 로딩 UI 및 오류 처리 문서를 참조하세요.