동적 라우트 생성

이전 장에서는 정적인 URL 경로를 가진 페이지를 만들고 연결하는 방법을 배웠습니다.

하지만 실제 서비스에서는 URL 일부가 데이터에 따라 동적으로 바뀌는 경우가 훨씬 많습니다.

예를 들어 블로그 상세(/blog/nextjs-basics), 상품 상세(/products/luxury-watch-xyz), 사용자 프로필(/users/alice) 같은 경로가 대표적입니다.

Next.js App Router는 이러한 요구사항을 충족시키기 위해 동적 라우트(Dynamic Routes) 기능을 제공합니다.

이 절에서는 동적 라우트를 생성하고, URL에서 동적인 값을 추출하여 페이지 컴포넌트에서 사용하는 방법에 대해 자세히 알아보겠습니다.

앞 장의 Next.js 학습 프로젝트에서 src/app/layout.tsx와 개발 명령을 먼저 확인합니다. 아래 실습은 같은 프로젝트의 라우트 파일을 만드는 작업입니다. 라우트 파일 이름, 브라우저가 요청한 URL, await params의 결과를 차례로 대조하면 값이 어디서 생겼는지 설명할 수 있습니다. 파일 이름의 대괄호는 URL에 그대로 입력하는 문자가 아닙니다.

이 장은 Next.js 16 App Router의 기본 설정을 기준으로 합니다. cacheComponents를 별도로 켠 경우의 추가 Suspense·캐시 요건은 여기서 다루지 않습니다.

동적 라우트의 개념과 필요성

정적 라우트가 /about이나 /dashboard/settings처럼 고정된 URL을 가진다면, 동적 라우트는 URL의 특정 부분이 변수처럼 작동합니다.

• 블로그 게시물: /blog/my-first-post, /blog/nextjs-deep-dive
• 상품 상세: /products/12345, /products/67890
• 사용자 프로필: /users/john-doe, /users/jane-smith

이러한 URL에서는 /blog/, /products/, /users/는 고정되어 있지만, 그 뒤의 my-first-post, 12345, john-doe와 같은 값은 각 항목에 따라 달라집니다.

Next.js는 이 동적인 부분을 감지하고, 해당 값을 페이지 컴포넌트로 전달하여 우리가 각기 다른 콘텐츠를 렌더링할 수 있도록 돕습니다.

동적 라우트 생성하기: 대괄호 [] 사용

Next.js App Router에서 동적 라우트 세그먼트를 정의하려면, 폴더 이름을 대괄호([])로 감쌉니다.

이 대괄호 안의 이름이 파라미터(Parameter)의 키(key)가 됩니다.

예를 들어, 블로그 게시물 상세 페이지를 만든다고 가정해 봅시다.

// src/app/blog/[slug]/page.tsx

interface BlogDetailPageProps {
  params: Promise<{
    slug: string; // [slug] 폴더 이름과 일치해야 합니다.
  }>;
}

// 서버 컴포넌트로 작동하며, params를 prop으로 받습니다.
export default async function BlogDetailPage({ params }: BlogDetailPageProps) {
  const { slug } = await params; // URL에서 slug 값을 추출

  // 실제 애플리케이션에서는 이 slug 값을 사용하여
  // 데이터베이스나 API에서 해당 게시물의 내용을 불러올 것입니다.
  // 예: const post = await getPostBySlug(slug);

  return (
    <div>
      <h1>블로그 게시물: {slug}</h1>
      <p>
        현재 보고 계신 게시물의 식별자(slug)는 <strong>{slug}</strong> 입니다.
      </p>
      <p>여기에 실제 게시물 내용이 표시됩니다.</p>
    </div>
  );
}

실습: 개발 서버가 실행 중인 상태에서 브라우저를 열고 다음 URL로 접속해 보세요.

• http://localhost:3000/blog/my-first-post
• http://localhost:3000/blog/nextjs-deep-dive
• http://localhost:3000/blog/welcome-to-my-blog

각 URL에 따라 페이지 제목과 내용에 slug 값이 다르게 표시되는 것을 확인할 수 있습니다.

다중 동적 라우트 세그먼트

하나의 라우트에 여러 개의 동적 세그먼트를 포함할 수도 있습니다.

예를 들어, 특정 카테고리 내의 블로그 게시물을 나타내는 /blog/[category]/[slug]와 같은 경로를 만들 수 있습니다.

다음은 앞의 한 세그먼트 예제와 별개의 설계입니다. 같은 blog 바로 아래에 [slug]와 [category]를 함께 두면 동적 키 이름이 충돌하므로 두 구조를 동시에 추가하지 마세요.

interface CategoryBlogDetailPageProps {
  params: Promise<{
    category: string; // [category] 폴더 이름과 일치
    slug: string;     // [slug] 폴더 이름과 일치
  }>;
}

export default async function CategoryBlogDetailPage({ params }: CategoryBlogDetailPageProps) {
  const { category, slug } = await params;

  return (
    <div>
      <h1>카테고리: {category}</h1>
      <h2>게시물: {slug}</h2>
      <p>
        이 게시물은 <strong>{category}</strong> 카테고리에 속하며, 식별자는 <strong>{slug}</strong> 입니다.
      </p>
    </div>
  );
}

실습: 이제 다음 URL로 접속해 보세요.

• http://localhost:3000/blog/web-dev/understanding-react
• http://localhost:3000/blog/frontend/nextjs-features

URL의 category와 slug 부분이 정확히 추출되어 페이지에 표시되는 것을 볼 수 있습니다.

예시: 폴더 이름과 URL 값을 한 쌍씩 대조하기

/blog/web-dev/understanding-react가 두 세그먼트 설계로 매칭되면, 고정 blog를 제외한 첫 값은 [category]에, 다음 값은 [slug]에 대응합니다. 따라서 await params 뒤의 값은 { category: 'web-dev', slug: 'understanding-react' }입니다. 폴더에 쓴 이름이 키이고 URL에 들어온 문자열이 값입니다. 동적 이름만 category에서 topic으로 바꾸면 URL 모양은 같아도 코드에서 읽어야 할 키는 달라집니다.

별도 설계 src/app/products/[productId]/reviews/[reviewId]/page.tsx로 /products/p-42/reviews/r-7?sort=recent를 받는다고 가정합니다. 페이지가 기다려야 하는 prop, 그 뒤의 두 키와 값, sort가 이 두 경로 값에 포함되는지를 예측하세요. 매칭 성공만으로 상품과 리뷰가 실제로 존재한다고 판단할 수도 있을까요?

generateStaticParams 함수

동적 라우트를 가진 페이지를 정적으로 생성(Static Site Generation, SSG)해야 할 때, Next.js는 빌드 시점에 어떤 params 값을 가지고 페이지를 생성할지 알아야 합니다.

이를 위해 generateStaticParams 함수를 사용합니다.

이 함수는 라우트의 page.tsx나 layout.tsx에서 내보낼 수 있습니다. 다음 코드는 처음의 blog/[slug]/page.tsx 예제에 추가합니다. 바로 앞의 다중 세그먼트 구조를 함께 추가하는 코드는 아닙니다.

// ... (BlogDetailPage 컴포넌트 코드) ...

// SSG를 위해 빌드 시 어떤 slug 값을 생성할지 명시
export async function generateStaticParams() {
  const posts = [
    { slug: 'my-first-post' },
    { slug: 'nextjs-deep-dive' },
    { slug: 'understanding-server-components' },
  ];

  // 반환 값은 { slug: '...' } 형태의 객체 배열이어야 합니다.
  return posts;
}

이 예제는 빌드 시 알려진 세 slug를 후보로 제공해 해당 경로를 사전 렌더합니다. 데이터나 런타임 API 사용에 따라 렌더링 방식은 달라질 수 있으므로, 함수가 있다는 사실만으로 모든 경로가 완전한 정적 HTML이 되는 것은 아닙니다.

목록에 없는 slug의 허용 여부는 dynamicParams로 정합니다. 기본값 true는 요청 시 처리를 허용하고, false는 미등록 경로를 허용하지 않습니다. 경로가 매칭되어도 실제 게시물이 없으면 데이터 조회 뒤 notFound() 같은 분기가 필요합니다.

개발 서버에서는 동적 경로를 방문할 때도 이 함수를 호출할 수 있습니다. 그러므로 npm run dev에서 제목이 바뀌었다는 확인과 프로덕션 빌드의 사전 렌더 결과 확인은 서로 다른 범위입니다. 등록되지 않은 slug를 시험할 때는 dynamicParams와 데이터 없음 분기를 함께 확인합니다.

next build는 관련 페이지·레이아웃을 생성하기 전에 이 함수를 호출합니다. ISR 재검증 중에는 generateStaticParams를 다시 실행하지 않습니다. 이 절에서는 API 규약과 코드 구성을 설명했으며 특정 로딩 시간은 측정하지 않았습니다.