App Router (1) - 라우팅, 쿼리스트링, URL 파라미터

2026.09.22 · 2분 읽기 · 조회 0

App Router

앱 라우터는 Next.js 13 버전에 새롭게 추가된, 기존의 Page Router를 완전히 대체하는 라우터다.

페이지 라우팅 설정 방식, 페이지 레이아웃 설정 방식, 데이터 페칭 방식 등이 변경되었으며, React 18의 신규 기능도 사용 가능하다.

네비게이팅, 프리페칭, 사전 렌더링 등의 기능은 크게 변경된 사항이 없다.

프로젝트 생성

npx create-next-app@15 .

이번엔 App Router 사용을 yes로 답해서 프로젝트를 생성한다.

page 폴더는 없어지고 app 폴더가 생겼다. 나머지는 페이지 라우터와 구조가 거의 똑같다.

페이지 라우팅

기존의 Page Router 에서는 pages 폴더 내부의 파일 명이 해당 페이지의 경로가 되었다.

App Router 에서는 페이지 파일의 이름은 무조건 page.tsx로 지어야 한다. 경로는 폴더명으로 지정하고 내부에 page.tsx를 만들어서 라우팅 해준다.

이는 동적 경로도 마찬가지이다.

쿼리스트링

// search/page.tsx
export default function Page(props) {
  return <div>Search 페이지</div>;
}

App Router에서는 /search?q=안녕 와 같은 경로에 존재하는 쿼리스트링은 메인 컴포넌트의 props 내부에 들어가게 된다. props를 콘솔에 찍어보면.

searchParams: Promise {
    <pending>,
    q: [Getter/Setter],
    [Symbol(async_id_symbol)]: 79179,
    [Symbol(trigger_async_id_symbol)]: 79173,
    [Symbol(kResourceStore)]: {
      isStaticGeneration: false,
      page: '/search/page',
      route: '/search',
      incrementalCache: [IncrementalCache] ...(생략)

다음과 같이 searchParams 값이 Promise로 들어있는 것을 확인할 수 있다.

params: Promise {
    {},
    [Symbol(async_id_symbol)]: 79256,
    [Symbol(trigger_async_id_symbol)]: 79255,
    [Symbol(kResourceStore)]: {
      isStaticGeneration: false,
      page: '/search/page',
      route: '/search',
      incrementalCache: [IncrementalCache] ...(생략)

url 파라미터 값도 역시 Promise 로 들어있다.

export default async function Page(
  {searchParams} : {searchParams : Promise<{q : string}>}
){
  console.log(await searchParams)
  return ()
}

때문에 내부에서 구조분해 할당을 이용해서 해당 값만 꺼내고, async/await을 통해서 해당 값을 이용할 수 있다.

URL Parameter

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
 
  return <div>book 페이지</div>;
}

앞서 쿼리스트링과 마찬가지로 프롭스에서 구조분해할당으로 꺼내온 후, async/await을 이용해 꺼내쓸 수 있다.

클라이언트 컴포넌트의 경우

"use client"
import { useSearchParams } from 'next/navigation';
 
const q = searchParams.get("q");

서버 컴포넌트와 달리 props를 받아올 수 없으므로, useSearchParams 훅을 이용해서 가져올 수 있다.

book/12/45 처럼 다수의 파라미터를 받고 싶을 땐 Page Router와 똑같이 Catch All Segment를 이용하면 된다.
book/[...id] 형식으로 폴더명을 지정한다.

/book 처럼 파라미터 값이 아예 없는 페이지도 매칭시키고 싶으면 [[...id]] 처럼 Optional Catch All Segment 를 사용한다.

댓글

giscus로 동작하며 GitHub Discussions에 저장됩니다.

관련 글