Next.js App Router 라우팅 & Proxy 완벽 이해하기

 

Next.js의 App Router는 단순히 페이지를 이동시키는 도구가 아닙니다.
기존의 라우팅 방식과는 달리, URL 구조 / UI 구조 / 사용자 경험 / 요청 흐름까지 하나의 시스템으로 통합하여 설계할 수 있도록 만들어진 구조입니다.

특히 Next.js 13 이후 도입된 App Router와, Next.js 16에서 변경된 proxy.ts 개념까지 이해하면
단순한 프론트엔드 개발을 넘어 애플리케이션 구조를 설계하는 관점을 가질 수 있게 될 것입니다.

---

App Router를 바라보는 관점

기존 React 프로젝트에서는 React Router를 사용하여 다음과 같이 라우팅을 구성했습니다.

• path를 코드로 선언
• 컴포넌트 단위로 페이지 구성
• 로딩/에러 상태를 각 컴포넌트에서 직접 처리

하지만 App Router는 접근 방식 자체가 다릅니다.

Next.js에서는 app 디렉터리 내부의 폴더 구조가 곧 URL 구조가 되며,
각 폴더 안의 특수 파일들이 해당 경로의 동작을 결정합니다.

이 구조의 핵심은 다음과 같습니다.

• 폴더 단위로 UI와 라우팅을 함께 설계
• 로딩, 에러, 404 처리를 구조적으로 분리
• 공통 레이아웃을 자연스럽게 재사용
• 서버 중심 렌더링과 스트리밍 기반 UX 구성

즉, App Router는 단순한 라우팅이 아니라
“경로 단위 UI 시스템”이라고 이해하는 것이 가장 정확합니다.

---

파일 기반 라우팅 심화

App Router에서는 디렉터리 구조가 곧 라우팅입니다.

예를 들어 다음과 같은 구조가 있다면:

app/
  page.tsx
  about/
    page.tsx

이 구조는 다음과 같이 매핑됩니다.

• / → app/page.tsx
• /about → app/about/page.tsx

이처럼 별도의 라우팅 설정 없이도,
파일 구조만으로 전체 라우팅이 자동으로 구성됩니다.

---

동적인 경로를 처리하고 싶을 경우에는 [param] 형태를 사용합니다.

app/blog/[slug]/page.tsx

이 구조는 /blog/hello-world, /blog/react-routing과 같은 URL을 처리하며,
slug 값은 컴포넌트에서 params로 전달받을 수 있습니다.

---

경로의 깊이가 일정하지 않을 경우에는 [...param]을 사용합니다.

app/docs/[...slug]/page.tsx

이 경우 /docs/a, /docs/a/b, /docs/a/b/c와 같은 모든 경로를 처리할 수 있으며,
값은 배열 형태로 전달됩니다.

---

경로가 존재할 수도 있고 존재하지 않을 수도 있다면 [[...param]]을 사용할 수 있습니다.

app/docs/[[...slug]]/page.tsx

이 구조는 /docs와 /docs/a/b를 모두 허용합니다.
즉, 리스트 페이지와 상세 구조를 하나로 묶을 수 있습니다.

---

Route Group은 (groupName) 형태로 구성됩니다.

app/
  (auth)/
    login/
      page.tsx
  (dashboard)/
    page.tsx

이때 (auth)와 (dashboard)는 URL에 포함되지 않습니다.

즉, URL은 다음과 같이 유지됩니다.

• /login
• /

Route Group은 다음과 같은 상황에서 매우 유용합니다.

• URL 구조를 유지하면서 폴더 구조를 분리하고 싶을 때
• 특정 영역에만 layout을 다르게 적용하고 싶을 때
• 대규모 프로젝트에서 기능 단위로 구조를 나누고 싶을 때

즉, Route Group은 단순한 문법이 아니라
프로젝트 구조 설계를 위한 핵심 도구입니다.

---

App Router의 특수 파일들

App Router의 강력함은 page.tsx가 아니라
특수 파일들을 통한 UX 설계에 있습니다.

 

layout.tsx

layout.tsx는 공통 UI를 정의합니다.

헤더, 사이드바, 네비게이션과 같은 요소를 포함하며,
페이지 이동 시에도 유지됩니다.

즉, 재사용되는 UI 뼈대를 담당합니다.

 

template.tsx

template.tsx는 layout과 비슷하지만,
페이지 이동 시마다 새로 렌더링됩니다.

따라서 다음과 같은 상황에 적합합니다.

• 페이지 진입 애니메이션
• 상태 초기화가 필요한 UI

loading.tsx

loading.tsx는 해당 경로의 로딩 상태를 정의합니다.

기존에는 컴포넌트 내부에서 isLoading으로 처리했다면,
App Router에서는 이를 파일 단위로 분리하여
route 단위로 로딩 UX를 설계할 수 있습니다.

 

error.tsx

error.tsx는 에러 경계 역할을 합니다.

전체 앱이 아닌, 특정 구간만 실패하도록 만들 수 있으며
재시도 UI나 fallback UI를 제공할 수 있습니다.

즉, 에러를 단순 예외가 아닌
구조적인 UX 요소로 다룰 수 있게 됩니다.

 

not-found.tsx

not-found.tsx는 단순한 404 페이지가 아닙니다.

• 존재하지 않는 URL
• 존재하지 않는 데이터

두 경우 모두 처리할 수 있습니다.

즉, 라우팅과 데이터 상태를 함께 다루는 중요한 파일입니다.

---

Parallel Routes

Parallel Routes는 하나의 layout 안에서
여러 UI 영역을 동시에 렌더링할 수 있게 해주는 기능입니다.

 

예를 들어 다음과 같은 구조를 만들 수 있습니다.

• 왼쪽 영역: 팀 정보
• 오른쪽 영역: 통계 데이터

이때 중요한 점은 단순히 컴포넌트를 나누는 것이 아니라
각 영역이 독립적인 라우팅 단위라는 것입니다.

즉, UI를 라우팅 기반으로 분리할 수 있습니다.

Intercepting Routes

Intercepting Routes는
다른 경로의 페이지를 현재 화면 위에 덮어 씌우는 방식으로 보여주는 기능입니다.

대표적인 예시는 다음과 같습니다.

• 게시글 목록에서 상세 클릭
• 전체 페이지 이동이 아닌 모달로 표시

즉, 동일한 URL이라도
진입 방식에 따라 UI가 달라질 수 있습니다.

이 기능의 핵심은
사용자의 맥락(Context)을 유지하는 것입니다.

---

proxy.ts — Next.js 16에서 가장 중요한 변화

Next.js 16에서는 기존의 middleware.ts가 proxy.ts로 변경되었습니다.

이 변화는 단순한 이름 변경이 아니라,
개념을 명확하게 정리하기 위한 중요한 변화입니다.

 

proxy.ts는 무엇인가?

proxy.ts는 요청이 애플리케이션 내부로 들어오기 전에 실행되는 파일입니다.

즉, 브라우저 → 서버 → App Router 진입 전 단계

에서 실행되는 로직입니다.

이 파일은 UI와는 전혀 관계가 없으며,
네트워크 레벨에서 요청을 제어하는 역할을 담당합니다.

proxy.ts의 핵심 역할

 

proxy.ts에서는 다음과 같은 작업을 수행할 수 있습니다.

• 인증 여부 확인
• 로그인 페이지로 리다이렉트
• 특정 URL을 다른 URL로 리라이트
• 요청 헤더 수정
• 쿠키 기반 접근 제어
• A/B 테스트 분기 처리
• 국가/언어 기반 라우팅

즉, proxy.ts는
“이 요청을 통과시킬 것인가, 어디로 보낼 것인가”를 결정하는 관문입니다.

왜 middleware가 아니라 proxy인가?

기존의 middleware라는 이름은 다음과 같은 오해를 만들었습니다.

• 모든 공통 로직을 여기에 넣어도 된다고 생각함
• 서버 로직처럼 사용하려고 함
• 비즈니스 로직까지 섞이는 경우 발생

하지만 Next.js는 이를 명확히 구분하기 위해
proxy라는 이름으로 변경했습니다.

이 파일은 요청을 중간에서 가로채고 방향을 바꾸는 역할이다

 

즉, proxy.ts는

• API 서버가 아니고
• 비즈니스 로직 처리 위치도 아니며
• UI 로직과도 완전히 분리된

“네트워크 경계 레이어”입니다.

proxy.ts의 위치와 실행 흐름

요청 흐름을 기준으로 보면 다음과 같습니다.

브라우저 요청
   ↓
proxy.ts 실행
   ↓
라우팅 결정 (App Router)
   ↓
페이지 렌더링

이 구조 덕분에 우리는 다음과 같은 설계를 할 수 있습니다.

• 페이지마다 인증 체크 X
• 진입 시 한 번만 인증 체크 O

---

실제 예시: 인증 보호

import { NextResponse } from 'next/server';

export function proxy(request) {
  const token = request.cookies.get('accessToken');

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*'],
};

이 코드는 /dashboard 경로에 접근할 때

• 토큰이 없으면 → /login으로 이동
• 있으면 → 정상 진행

을 처리합니다.

이 방식의 장점은 매우 명확합니다.

• 각 페이지에서 인증 체크를 반복하지 않아도 됨
• 인증 로직이 한 곳에 모임
• 코드가 훨씬 단순해짐

proxy.ts를 사용할 때 주의할 점

proxy.ts는 강력하지만, 잘못 사용하면 성능과 구조를 망칠 수 있습니다.

다음 원칙을 지키는 것이 중요합니다.

• X 비즈니스 로직 넣지 않기
• X DB 접근하지 않기
• X 무거운 연산 하지 않기
• O 가벼운 조건 분기만 처리하기
• O 라우팅/접근 제어에 집중하기

즉, proxy.ts는
빠르고 가벼운 게이트 역할만 해야 합니다.

---

마무리

Next.js App Router는 단순한 라우팅 도구가 아닙니다.

• 파일 구조 기반 라우팅
• 레이아웃 중심 UI 설계
• 로딩/에러/404의 구조적 처리
• 병렬 렌더링과 인터셉트 기반 UX
• 그리고 proxy를 통한 네트워크 경계 제어

이 모든 요소들이 결합되어
훨씬 구조적이고 확장 가능한 애플리케이션을 만들 수 있게 해줍니다.

특히 proxy.ts까지 이해하게 되면,
단순히 “페이지를 만드는 개발자”가 아니라

“요청 흐름과 UI 구조를 함께 설계하는 개발자”로 한 단계 성장하게 됩니다.

 

 

감사합니다!