2nd/10_Wiki/Topics/Next.js_App_Router.md

---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[Next.js App Router 프로젝트|Next.js App Router 프로젝트]]
last_updated: 2026-05-02
---

# [[Next.js App Router 프로젝트|Next.js App Router 프로젝트]]

## 📌 Brief Summary
[[Next.js App Router|Next.js App Router]] 프로젝트는 React Server Components(RSC)를 기반으로 동작하기 때문에 기존의 런타임 CSS-in-JS(예: [[styled-components|styled-components]], Emotion) 라이브러리와는 호환되지 않아 스타일링 아키텍처의 변화가 필수적입니다 [1, 2]. 실무에서 유지보수성과 확장성을 확보하기 위해 스타일링은 **Tailwind CSS**, **[[CSS Modules|CSS Modules]]** 또는 빌드 타임 기반의 **[[vanilla-extract|vanilla-extract]]**를 사용하는 것이 권장됩니다 [2, 3]. 더불어 대규모 애플리케이션으로 확장하기 위해서는 `app/` 디렉토리에 모든 코드를 넣는 대신, 라우팅과 비즈니스 로직을 분리하는 **기능 주도(Feature-Driven)** 형태의 모듈러 폴더 구조를 채택해야 합니다 [4, 5].

---

[[Next.js App Router|Next.js App Router]] 환경에서는 React Server Components(RSC)와의 호환성 문제로 인해 기존의 런타임 CSS-in-JS(예: [[styled-components|styled-components]], Emotion) 사용이 부적합합니다 [1, 2]. 대신 확장성과 유지보수성을 위해 런타임 오버헤드가 없는 Tailwind CSS, [[CSS Modules|CSS Modules]], 또는 vanilla-extract와 같은 [[Zero-Runtime CSS-in-JS|Zero-Runtime CSS-in-JS]]의 사용이 권장됩니다 [2, 3]. 더불어 성공적인 컴포넌트 스타일링과 관리를 위해서는 라우팅 구조와 비즈니스 로직 및 UI 컴포넌트를 분리하는 기능 기반(Feature-Driven) 아키텍처의 도입이 필수적입니다 [4].

---

[[Next.js|Next.js]] App Router는 [[React Server Components|React Server Components]](RSC)를 핵심 아키텍처로 도입하여 기존의 클라이언트 측 렌더링 중심의 개발 방식에서 벗어난 새로운 패러다임을 제공하는 라우팅 시스템입니다 [1]. 기본적으로 모든 컴포넌트가 서버 컴포넌트로 동작하여 서버에서 HTML을 완전히 렌더링하며, 상태 관리나 이벤트 핸들러 등 상호작용이 필요한 경우에만 'use client' 지시어를 사용해 클라이언트 컴포넌트를 분리합니다 [2, 3]. 이러한 아키텍처 변화는 애플리케이션의 성능과 보안을 향상시키지만, 기존의 상태 및 컨텍스트 기반 스타일링 접근 방식에 중대한 영향을 미칩니다 [4, 5].

## 📖 Core Content
*   **스타일링 전략 및 CSS 아키텍처**
    *   [[Next.js|Next.js]] App Router는 서버에서 HTML을 스트리밍하는 **React Server Components(RSC)**를 사용하므로, [[React Context|React Context]]에 의존하는 런타임 CSS-in-JS는 기능할 수 없으며 App Router를 사용하는 새 프로젝트에는 권장되지 않습니다 [1, 2, 6]. 
    *   따라서 런타임 오버헤드가 없는 **Tailwind CSS**나 로컬 스코프를 보장하는 **CSS Modules**, 혹은 타입 안정성을 지니면서도 런타임 오버헤드가 0인 **vanilla-extract**를 선택하는 것이 현재 권장되는 방식입니다 [2, 3].
    *   페이지 라우터(Pages Router)에서 작동하던 기존 styled-components 프로젝트를 App Router로 마이그레이션 할 때는 이와 같은 새로운 CSS 접근 방식으로의 전환 계획이 필요합니다 [3].

*   **유지보수 가능한 폴더 구조 ([[Feature-Driven Architecture|Feature-Driven Architecture]])**
    *   App Router 사용 시 흔히 하는 가장 큰 실수는 컴포넌트, 훅, 비즈니스 로직을 `app/` 디렉토리에 라우트와 함께 전부 몰아넣는 것입니다 [4]. 프로젝트가 커지면 이는 관리 불가능한 상태가 됩니다 [4].
    *   `app/` 폴더 내의 파일(예: `page.tsx`, `layout.tsx`)은 오로지 라우팅 및 레이아웃 처리만을 위해 최대한 가볍게 유지해야 합니다 [5, 7].
    *   실제 비즈니스 로직은 `src/features/` 내에 도메인이나 기능 단위(예: `market-data`, `user-profile`)로 묶어 분리해야 합니다 [4, 5, 7, 8]. 이렇게 하면 데이터를 불러오는 작업과 UI 표현을 깨끗하게 분리할 수 있으며, 버그 발생 시 거대한 전역 폴더를 뒤질 필요 없이 특정 기능 폴더 내부만 확인하면 되므로 유지보수가 훨씬 쉬워집니다 [5, 9].

*   **실무 팁 및 표준화 설정**
    *   프로젝트 초기화 시 `src/` 디렉토리를 사용하여 `tailwind.config.ts` 등 설정 파일과 소스 코드를 분리하는 것이 좋습니다 [10].
    *   깔끔한 코드 작성을 위해 `tsconfig.json`에서 절대 경로(`@/components/...`)를 설정하여 수많은 상대 경로(`../../../`) 작성을 방지해야 합니다 [7, 10, 11].
    *   API 호출을 기능별로 중앙 집중화하고 공유 폴더의 컴포넌트를 재사용하는 등 계층을 나누면 확장 및 리팩토링 시 안전성이 매우 높아집니다 [7, 8].

---

*   **React [[Server Components|Server Components]](RSC)와의 호환성 한계**
    [[Next.js|Next.js]] App Router 환경은 브라우저가 아닌 서버에서 실행되어 HTML을 스트리밍하는 React Server Components(RSC)를 활용합니다 [2]. styled-components나 Emotion과 같은 기존의 컨텍스트 기반 런타임 CSS-in-JS 라이브러리들은 서버 컴포넌트에 React 컨텍스트가 존재하지 않기 때문에 근본적으로 호환되지 않으며, 이 환경에서는 런타임 CSS-in-JS의 사용이 문제(problematic)가 됩니다 [1, 2].

*   **App Router 환경에 권장되는 스타일링 전략**
    새로운 Next.js App Router 프로젝트를 구축하거나 기존 프로젝트를 App Router로 마이그레이션할 때는 런타임 CSS-in-JS를 피해야 합니다 [3]. 대신 다음의 세 가지 접근 방식 중 하나를 채택하는 것이 권장됩니다 [2, 3].
    *   **Tailwind CSS**: 런타임 오버헤드가 전혀 없으며, 중소규모 앱에서 컴포넌트 원시 요소(예: shadcn/ui)와 결합하여 사용하기에 적합합니다 [3, 5].
    *   **CSS Modules**: 복잡한 애니메이션을 구현하거나 CSS 기술 역량이 강한 팀에게 적합하며 런타임 비용이 발생하지 않습니다 [3, 5].
    *   **Zero-runtime CSS-in-JS (vanilla-extract)**: 빌드 타임에 정적 CSS를 생성하여 RSC와 호환되며, 여러 테마를 가진 대규모 디자인 시스템에서 타입 안전성을 확보하며 스타일링하기에 가장 적합합니다 [3, 5].

*   **확장 가능한 컴포넌트 폴더 구조 설계**
    App Router 환경에서 컴포넌트와 스타일을 유지보수 가능하게 관리하려면, `app/` 디렉토리에 라우트, 컴포넌트, 훅(hooks), 로직을 모두 섞어 넣는 실수를 피해야 합니다 [4]. `app/` 폴더는 라우팅과 레이아웃 관리에만 엄격히 사용하고, 실제 스타일이 적용된 UI 컴포넌트와 비즈니스 로직은 `src/features/`와 같은 디렉토리에 도메인별(Feature-Driven)로 분리하여 캡슐화하는 것이 장기적인 확장성에 유리합니다 [4, 6, 7].

---

* **React [[Server Components|Server Components]](RSC) 모델의 작동 방식**
  [[Next.js 15 App Router|Next.js 15 App Router]] 환경에서 서버 컴포넌트는 클라이언트로 JavaScript 코드를 전송하지 않으며, 서버에서 직접 데이터를 패칭하여 렌더링된 HTML만을 브라우저로 보냅니다 [2]. 반면 동적 상태 변경, 브라우저 API 접근, 이벤트 리스너가 필요한 인터랙티브 UI는 파일 최상단에 `'use client'`를 명시하여 클라이언트 컴포넌트 경계(Client Component Boundary)를 설정해야 합니다 [3]. 하이드레이션([[Hydration|Hydration]]) 프로세스는 이러한 클라이언트 컴포넌트에 대해서만 수행되어 인터랙티비티를 활성화합니다 [6].

* **스타일링 패러다임의 충돌 및 권장 사항**
  RSC는 서버 전용 실행 환경으로, [[React Context|React Context]]를 사용할 수 없습니다 [7, 8]. 이는 테마나 상태를 위해 Context API에 의존하는 런타임 CSS-in-JS 라이브러리([[styled-components|styled-components]], Emotion 등)가 App Router에서 기본적으로 작동하지 않는 문제를 발생시켰습니다 [4, 7, 8]. 따라서 Next.js App Router를 사용하는 최신 프로젝트에서는 런타임 오버헤드 없이 빌드 타임에 정적 CSS를 생성하는 **Tailwind CSS**, **[[CSS Modules|CSS Modules]]**, 혹은 **vanilla-extract**([[Zero-Runtime CSS-in-JS|Zero-Runtime CSS-in-JS]])의 도입이 강력히 권장됩니다 [8-10].

* **CSS-in-JS 지원 및 레지스트리 패턴**
  [[Next.js 15|Next.js 15]]는 런타임 CSS-in-JS 라이브러리를 사용할 수 있도록 렌더링 중 CSS 규칙을 수집하고 이를 HTML의 `<head>`에 주입(`useServerInsertedHTML` 훅 활용)하는 **[[Style Registry|Style Registry]] 패턴**을 지원합니다 [11]. 그러나 서버와 클라이언트의 클래스명 불일치(Hydration Mismatch)를 방지하기 위한 추가 설정(예: `next.config.js` 내 컴파일러 옵션)이 요구됩니다 [12]. 최신 `styled-components` (v6.3.0 이상)의 경우, RSC 환경을 자동 감지하여 별도의 설정 없이 인라인 `<style>` 태그를 방출하는 RSC 지원 업데이트를 추가하기도 했습니다 [13]. 

* **렌더링 및 데이터 패칭 최적화 전략**
  App Router는 사용 사례에 최적화하기 위해 빌드 타임에 미리 정적 HTML을 렌더링하는 정적 렌더링(Static Rendering, 기본값) 외에, 동적 렌더링(Dynamic Rendering), 점진적 정적 재생성(ISR, Incremental Static Regeneration) 등의 다양한 전략을 제공합니다 [14]. 데이터 패칭 시에도 병렬(Parallel) 데이터 패칭, 의존성에 따른 순차적(Sequential) 패칭, 그리고 React Suspense를 결합해 콘텐츠를 점진적으로 보여주는 스트리밍(Streaming) 패턴을 구성할 수 있습니다 [15].

## ⚖️ Trade-offs & Caveats
No trade-offs available.

## 🔗 Knowledge Connections
- **Related Topics:** [[React Server Components|React Server Components]], Tailwind CSS, CSS Modules, [[vanilla-extract|vanilla-extract]], [[Feature-Driven Architecture|Feature-Driven Architecture]]
- **Projects/Contexts:** [[실무에서 CSS 관리하는 방법|실무에서 CSS 관리하는 방법]], [[대규모 프론트엔드 프로젝트 아키텍처|대규모 프론트엔드 프로젝트 아키텍처]]
- **Contradictions/Notes:** 기존에 Pages Router와 styled-components로 잘 작동하고 있는 프로젝트라면 굳이 마이그레이션 할 필요는 없으나, App Router로 전환하고자 할 경우 반드시 Tailwind, CSS Modules, vanilla-extract 중 하나로의 마이그레이션을 계획해야 합니다 [3].

---
*Last updated: 2026-04-26*

---

- **Related Topics:** [[CSS Modules|CSS Modules]], Tailwind CSS, CSS-in-JS, [[React Server Components|React Server Components]]
- **Projects/Contexts:** 신규 Next.js App Router 프로젝트 환경 설정, 기존 React 프로젝트의 App Router 마이그레이션 전략, 기능 기반 아키텍처([[Feature-Driven Architecture|Feature-Driven Architecture]])
- **Contradictions/Notes:** 컴포넌트 상태와 프롭스(props)에 기반한 동적 스타일링에 매우 유용하게 쓰이던 styled-components와 Emotion 같은 런타임 CSS-in-JS 기술들이 과거에는 훌륭한 개발자 경험을 제공했지만, Next.js App Router라는 최신 패러다임 하에서는 RSC와의 비호환성 및 런타임 성능 비용으로 인해 권장되지 않는 기술로 전환되었다는 점이 가장 큰 대조를 이룹니다 [1, 3, 8].

---
*Last updated: 2026-04-26*

---

- **Related Topics:** [[React Server Components|React Server Components]], Tailwind CSS, Styled Components, [[Zero-Runtime CSS-in-JS|Zero-runtime CSS-in-JS]], [[Hydration|Hydration]]
- **Projects/Contexts:** Modern [[Frontend|Frontend]] Engineering, Scalable Frontend [[Architecture|Architecture]]
- **Contradictions/Notes:** 소스 전반에서 기존 런타임 CSS-in-JS 라이브러리(styled-components 등)가 React Context 부재로 인해 Next.js App Router(RSC) 환경과 호환되지 않아 Tailwind CSS나 정적 CSS 방식이 권장된다고 설명합니다 [4, 7, 10]. 그러나 `styled-components`의 릴리스 노트를 보면 v6.3.0 이후부터 RSC 환경을 자동으로 감지하고 인라인 `<style>` 태그를 자체적으로 방출 및 병합하여 RSC 및 App Router에서도 정상 동작하도록 패치되었습니다 [13]. 

---
*Last updated: 2026-04-26*