Next.js 병렬 라우터(Parallel Routes) 적용하기

---

Next.js 병렬 라우트(Parallel Routes) 적용하기

1. 병렬 라우트란 무엇인가

1-1. 개념 및 동작 원리

• Next.js의 병렬 라우트(Parallel Routes)는 하나의 페이지 내에서 여러 개의 독립적인 UI 영역을 동시에 렌더링할 수 있도록 지원하는 기능이다.
• 각 병렬 라우트는 별도의 폴더(@ 접두사)를 통해 구현하며, 서로 독립적으로 동작한다.
• 이를 통해 복잡한 레이아웃이나, 여러 개의 동적 패널을 동시에 관리할 수 있다.

2. 병렬 라우트 폴더 구조 및 네이밍 규칙

2-1. 폴더 구조 설계

• 병렬 라우트를 사용하려면, app 디렉토리 하위에 @로 시작하는 폴더를 생성해야 한다.

  src/app/main/
    layout.tsx
    page.tsx
    @quest/
      page.tsx
    @creation/
      page.tsx
      default.tsx

• 각 병렬 라우트 폴더에는 반드시 page.tsx 또는 default.tsx 파일이 포함되어야 한다.

2-2. 네이밍 규칙 및 주의사항

• 폴더명은 반드시 @로 시작해야 하며, 명사형 단어(예: @creation, @quest)를 사용하는 것이 가장 바람직하다.
• 케밥 케이스(@create-quest)와 같이 하이픈이 포함된 이름은 Next.js에서 병렬 라우트로 인식하지 못해 오류가 발생할 수 있다.
• 병렬 라우트의 props 이름은 폴더명에서 @를 뺀 camelCase로 layout에 전달된다.

  export default function Layout({ children, quest, creation }: {
    children: React.ReactNode;
    quest: React.ReactNode;
    creation: React.ReactNode;
  }) { ... }

3. 병렬 라우트 조건부 렌더링 구현

3-1. 쿼리 파라미터를 활용한 조건부 렌더링

• 특정 버튼 클릭 시 쿼리 파라미터를 변경하여, 병렬 라우트의 렌더링을 제어할 수 있다.

  // QuestList.jsx
  const handleCreateClick = () => {
    router.push("/main?mode=creation");
  };

• layout.tsx에서는 useSearchParams 훅을 사용하여 쿼리 파라미터 값을 읽고, 조건에 따라 병렬 라우트를 렌더링한다.

  import { useSearchParams } from "next/navigation";
  // ...
  const searchParams = useSearchParams();
  const isCreation = searchParams.get("mode") === "creation";
  // ...
  {
    isCreation ? creation : quest;
  }

3-2. 클라이언트 컴포넌트 분리의 필요성

• useSearchParams와 같은 훅은 클라이언트 컴포넌트에서만 사용할 수 있다.
• layout.tsx가 서버 컴포넌트일 경우, 해당 부분만 별도의 클라이언트 컴포넌트로 분리하는 것이 권장된다.

  // MainContentSwitcher.jsx
  "use client";
  import { useSearchParams } from "next/navigation";
  export default function MainContentSwitcher({ quest, creation }) {
    const searchParams = useSearchParams();
    const isCreation = searchParams.get("mode") === "creation";
    return isCreation ? creation : quest;
  }

4. 실전에서 겪은 주요 오류와 해결 방법

4-1. 폴더명 오류

• 케밥 케이스(@create-quest)로 폴더를 생성하면, Next.js가 병렬 라우트로 인식하지 못하고 아래와 같은 오류가 발생한다.

  Module parse failed: Unexpected token (24:14)

• 해결 방법은 폴더명을 @creation과 같이 명사형 단일 단어로 변경하는 것이다.

4-2. 클라이언트 훅 사용 오류

• layout.tsx에서 useSearchParams를 사용하면 아래와 같은 오류가 발생한다.

  Error:   × You're importing a component that needs `useSearchParams`. This React hook only works in a client component. To fix, mark the file (or its parent) with the `"use client"` directive.

• 해결 방법은 해당 훅을 사용하는 부분을 별도의 클라이언트 컴포넌트로 분리하는 것이다.

4-3. 캐시 문제

• 구조 변경 후에도 오류가 계속된다면, .next 폴더를 삭제하고 개발 서버를 재시작해야 한다.

  rm -rf .next
  npm run dev

5. 병렬 라우트 활용 팁 및 결론

5-1. 쿼리 파라미터 네이밍 팁

• 쿼리 파라미터는 mode=creation과 같이 명확하고 의미 있는 이름을 사용하는 것이 좋다.

5-2. 병렬 라우트의 장점

• 복잡한 UI를 독립적으로 관리할 수 있어, 유지보수성과 확장성이 크게 향상된다.

5-3. 결론

• Next.js의 병렬 라우트는 강력한 기능이지만, 폴더명 규칙과 클라이언트/서버 컴포넌트 구분 등 몇 가지 주의사항을 반드시 숙지해야 한다.
• 실전에서 겪은 오류와 해결 경험을 바탕으로, 구조 설계와 네이밍, 컴포넌트 분리 원칙을 잘 지키면 생산성 높은 개발이 가능하다.
• 특히, 동사 대신 명사형 폴더명을 사용하면 Next.js의 라우팅 시스템과 더 잘 어울리며, 유지보수와 협업에 유리하다.

공식 문서 한글 번역: https://nextjs-ko.org/docs

---