# [[Next.js App Router]]

## 📌 Brief Summary
Next.js App Router는 Next.js 13.4 버전 이상에서 새롭게 도입된 라우팅 및 아키텍처 시스템으로, 'app'이라는 폴더를 기반으로 경로(Route)를 정의합니다 [1, 2]. 기본적으로 모든 컴포넌트를 React Server Components(RSC)로 취급하여 클라이언트로 전송되는 자바스크립트 번들 크기를 줄이고, 하이드레이션(Hydration) 없이 빠른 페이지 상호작용을 가능하게 합니다 [1, 3, 4]. 상태 관리나 브라우저 API가 필요한 인터랙티브 UI의 경우에만 `'use client'` 지시어를 명시하여 클라이언트 컴포넌트로 전환하는 방식으로 작동합니다 [1, 5].

## 📖 Core Content

*   **서버 컴포넌트(RSC) 우선 접근법**
    App Router의 모든 페이지와 컴포넌트는 기본적으로 서버 컴포넌트(RSC)로 동작합니다 [1, 5]. 이들은 클라이언트로 자바스크립트 코드를 전송하지 않으며, 서버에서 렌더링된 후 직렬화된 JSON 형태의 'RSC 페이로드(payload)'로 클라이언트에 스트리밍됩니다 [6-8]. 반면 클라이언트 컴포넌트는 RSC 페이로드 내에 번들러가 인식하는 참조(reference) 형태로 포함되며, 실제 클라이언트의 자바스크립트 번들 크기에 영향을 줍니다 [9, 10].
*   **데이터 페칭과 서버 액션(Server Actions)**
    서버 컴포넌트는 비동기(`async`) 함수로 작성될 수 있어 컴포넌트 내부에서 직접 데이터베이스에 접근하거나 파일 시스템을 읽는 등의 데이터 페칭이 가능합니다 [11-13]. 사용자의 상호작용에 의해 데이터를 변경(Mutation)할 때는 `'use server'` 지시어를 사용하는 서버 액션(Server Actions)을 활용하여 API 라우트 구축 없이 서버에서 작업을 직접 수행합니다 [14, 15].
*   **클라이언트/서버 컴포넌트 교차 배치(Interleaving)**
    서버 컴포넌트 내에 클라이언트 컴포넌트를 배치할 수 있지만, 반대로 클라이언트 컴포넌트 파일 내에서 서버 컴포넌트를 직접 임포트하면 해당 서버 컴포넌트는 암시적으로 클라이언트 컴포넌트로 변환됩니다 [16, 17]. 이러한 제약을 피하기 위해 서버 컴포넌트를 클라이언트 컴포넌트의 `children` 프로프(prop)로 넘겨서 렌더링하게 하는 패턴 구조를 사용해야 합니다 [18, 19]. 
*   **스트리밍(Streaming)과 Suspense의 결합**
    App Router에서는 비동기 데이터의 로딩 속도가 다를 때 `Suspense` 경계를 활용하여 부분적인 스트리밍을 지원합니다 [20, 21]. 느린 데이터 쿼리가 전체 페이지 렌더링을 차단하지 않도록, 완료된 부분(예: 헤더 등)을 먼저 화면에 그리고 나머지 데이터를 백그라운드에서 스트리밍하여 로딩 상태를 점진적으로 대체합니다 [20, 22].

## ⚖️ Trade-offs & Caveats

*   **캐싱 및 재검증 비효율성**: 서버 액션을 통해 데이터를 업데이트한 뒤 `revalidateTag`를 호출할 경우, 특정 데이터만 리로드되는 것이 아니라 현재 페이지의 전체 RSC 트리가 서버에서 다시 렌더링되는 비효율이 발생합니다 [23, 24].
*   **서버 액션의 직렬(Serial) 실행 병목**: 서버 액션은 한 번에 하나씩 직렬로 실행되며 병렬 처리가 불가능합니다 [25]. 네트워크 상태가 불안정하거나 고의로 요청을 늦출 경우 여러 번의 저장이 큐(Queue)에 막혀 심각한 성능 저하를 초래할 수 있습니다 [25].
*   **심각한 보안 취약점 위험 (React2Shell)**: 개발자들이 서버 액션을 내부 로컬 함수처럼 생각하기 쉽지만, 실제로는 누구나 POST 요청을 보낼 수 있는 공개 HTTP 엔드포인트입니다 [26]. 클라이언트에서 넘어온 입력값을 엄격히 유효성 검사(validation)하지 않을 경우, 원격 코드 실행(RCE)이나 소스 코드 유출 등의 치명적인 취약점(예: CVE-2025-55182)이 발생할 수 있습니다 [26-28].
*   **라우팅 중돌 현상**: `react-query` 등과 결합하여 `router.push`로 URL의 쿼리 스트링을 변경할 경우, Next.js가 새 경로로 간주하여 변경되지 않은 RSC 페이지를 불필요하게 렌더링하고 중복 네비게이션을 시도하는 문제가 있습니다 [29]. 대안인 `history.pushState`를 쓰면 UI 전환 처리가 중단되는 버그가 존재합니다 [30].
*   **구조적 복잡성**: 클라이언트/서버 컴포넌트의 경계를 나누고, Context API를 조심스럽게 사용해야 하는 등 기존 React 개발보다 아키텍처 구성과 인체공학적(ergonomic) 복잡성이 크게 증가합니다 [31].

## 🔗 Knowledge Connections

### Related Concepts

#### [관계 유형 A: 아키텍처/기반 기술]
*   [[React Server Components]]
    *   연결 이유: Next.js App Router가 채택한 핵심 렌더링 패러다임으로, 클라이언트 자바스크립트 번들을 줄이고 서버 자원을 직접 활용하기 위한 기반입니다 [32-34].
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: RSC 페이로드(payload)의 직렬화 과정과 하이드레이션(Hydration) 없이 렌더링되는 내부 메커니즘을 파악할 수 있습니다 [4, 8, 35].
*   [[Suspense 및 Streaming]]
    *   연결 이유: 데이터 패칭으로 인한 워터폴(Waterfall)을 방지하고 비동기적으로 UI를 청크(chunk) 단위로 스트리밍하기 위한 핵심 기술입니다 [20, 21].
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 준비 시간에 구애받지 않고 App Router가 빠른 최초 렌더링(First Paint)을 달성하는 비동기 렌더링 파이프라인을 이해할 수 있습니다 [36, 37].

#### [관계 유형 B: 구현/활용 도구]
*   [[Server Actions]]
    *   연결 이유: App Router 환경에서 데이터베이스 쓰기나 업데이트 같은 데이터 변경(Mutation)을 위해 별도의 API 라우트 없이 직접 호출하는 기능입니다 [14, 15].
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 단순한 함수 호출 이면의 HTTP 통신 원리와, 왜 서버 액션에 대해 전통적인 API 수준의 보안 유효성 검사가 필요한지 이해할 수 있습니다 [26, 38].
*   [[Client Components]]
    *   연결 이유: 상태(State), 부수 효과(Effect), 이벤트 핸들러 등 브라우저 기능이 필요한 UI 렌더링을 처리하며 `'use client'` 지시어로 정의됩니다 [3, 12].
    *   이 개념을 통해 더 깊게 이해할 수 있는 부분: 서버 컴포넌트와의 교차 배치(Interleaving) 시 발생하는 컴포넌트 트리의 렌더링 경계 규칙과, 불필요한 번들 증가를 막기 위한 분리 전략을 배울 수 있습니다 [17, 19, 39].

### Deeper Research Questions
*   클라이언트 컴포넌트가 서버 컴포넌트를 자식(`children`) 프로프로 전달받을 때, 직렬화(Serialization) 제약은 어떻게 극복되며 React 내부 파이버(Fiber) 트리는 어떻게 이들을 병합하는가?
*   서버 액션 사용 시 데이터 무효화(`revalidateTag`)가 전체 페이지 렌더링을 유발하는 비효율을 최소화하기 위해, Next.js의 캐싱 메커니즘을 튜닝하거나 대체할 수 있는 아키텍처 패턴은 무엇인가?
*   외부 전역 상태 관리 라이브러리(예: `react-query`)와 Next.js App Router의 라우터를 함께 사용할 때 URL 상태 동기화 충돌 문제를 해결하기 위한 베스트 프랙티스는 무엇인가?
*   서버 컴포넌트에서 클라이언트 컴포넌트로 전달되는 데이터는 RSC 페이로드를 통해 브라우저 네트워크 탭에 모두 노출되는데, 이를 방지하기 위한 데이터 필터링(Data Sanitization) 자동화 전략은 무엇인가?
*   무분별하게 `'use client'`를 남용하는 현상(Vibe Coding RSC Trap)을 피하기 위해, 개발 초기 단계부터 애플리케이션의 어느 영역을 클라이언트와 서버 컴포넌트로 분리할지 결정하는 도메인 주도 기준은 무엇인가?

### Practical Application Contexts
*   **Implementation:** 복잡한 상호작용이 없는 제품 설명, 내비게이션, 푸터 등 정적인 부분은 모두 서버 컴포넌트로 남겨두고, 상태나 브라우저 이벤트가 필요한 폼이나 버튼 요소만 최소한으로 분리하여 클라이언트 컴포넌트(`'use client'`)로 감싸 번들 크기를 최적화합니다 [40-42].
*   **System Design:** 별도의 REST API 레이어를 거치지 않고, 서버 컴포넌트에서 직접 파일 시스템이나 데이터베이스를 조회하여 컴포넌트를 렌더링하는 통합형 백엔드-프론트엔드 아키텍처로 설계합니다 [12, 13].
*   **Operation / Maintenance:** 서버 액션을 구현할 때, 반드시 '외부에 공개된 HTTP 엔드포인트'로 간주하고 조작 요청(Mutation)의 모든 인자값을 철저하게 유효성 검증(validation)하는 보안 검사 프로세스를 운영 지침으로 강제해야 합니다 [26, 38].
*   **Learning Path:** SSR과 클라이언트 렌더링의 병목점 이해 [43, 44] → RSC의 개념과 직렬화 가능성 제약 파악 [7, 45] → 클라이언트/서버 컴포넌트 경계(`children` 활용법) 학습 [18, 19] → 서버 액션의 보안 위험성 인지 순으로 단계적 학습을 진행합니다 [26].
*   **My Project Relevance:** 현재 대규모 React 기반 애플리케이션의 초기 로딩 성능(FCP) 저하를 해결하고자 할 때, 단순히 SSR을 도입하는 것을 넘어 App Router 기반의 서버 컴포넌트를 활용함으로써 클라이언트 측에 내려가는 자바스크립트 비용을 제거하는 솔루션으로 즉각 고려할 수 있습니다 [38, 40, 46].

### Adjacent Topics
*   [[React Hydration]]
    *   확장 방향: SSR 환경에서 정적 HTML이 동작하기 위해 필요한 이벤트 연결 과정으로, 이로 인해 발생하는 병목과 RSC가 이 한계를 어떻게 구조적으로 회피하는지 비교 조사합니다 [35, 43, 44].
*   [[Next.js Caching Architecture]]
    *   확장 방향: App Router의 강력하지만 복잡한 기본 캐시 동작 방식과, 서버 데이터 패칭 후 무효화 과정이 어떻게 이뤄지는지 세부 원리를 탐구합니다 [13, 24].

---
*Last updated: 2026-05-03*