# [[Next.js App Router Migration|Next.js App Router Migration]]

## 📌 Brief Summary
[[Next.js App Router|Next.js App Router]] 마이그레이션은 React Server Components(RSC)를 중심으로 프론트엔드 아키텍처의 패러다임이 전환되는 과정을 의미합니다 [1]. 이는 클라이언트 측 렌더링에 의존하던 기존 방식에서 벗어나, 컴포넌트가 브라우저로 JavaScript를 전송하지 않고 서버에서 실행되도록 하여 성능과 보안을 최적화합니다 [2]. 특히 런타임 [[CSS-in-JS|CSS-in-JS]] 라이브러리가 서버 컴포넌트 환경과 충돌하는 문제를 해결하기 위해, 정적 스타일링 방식이나 스타일 레지스트리([[Style Registry|Style Registry]]) 패턴을 도입하는 것이 주요 마이그레이션 과제입니다 [3, 4].

## 📖 Core Content
* **App Router와 RSC 아키텍처의 변화:**
  [[Next.js|Next.js]] App Router는 서버 컴포넌트([[Server Components|Server Components]])를 기본으로 사용하는 근본적인 변화를 가져왔습니다 [1, 5]. 서버 컴포넌트는 클라이언트로 JavaScript를 보내지 않으므로 번들 크기를 줄이고 성능을 향상시킵니다 [2, 6]. 상호작용이나 상태 관리가 필요한 경우에만 명시적으로 `'use client'` 지시어를 사용하여 클라이언트 컴포넌트 경계를 설정해야 합니다 [6, 7].
* **스타일링 패러다임의 전환 (The RSC Problem):**
  RSC는 브라우저가 아닌 서버에서 실행되므로 [[React Context|React Context]]를 사용할 수 없습니다 [3]. 이로 인해 Styled Components나 Emotion과 같이 Context 기반 런타임 테마 주입에 의존하는 CSS-in-JS 라이브러리들과 본질적인 호환성 문제(RSC Problem)가 발생했습니다 [3, 8]. 따라서 App Router 기반의 새로운 프로젝트로 마이그레이션할 때는 런타임 오버헤드가 없는 Tailwind CSS나 [[CSS Modules|CSS Modules]], 빌드 타임에 정적 CSS를 생성하는 [[vanilla-extract|vanilla-extract]]로 전환하는 것이 강력하게 권장됩니다 [3, 9, 10].
* **Styled Components의 App Router 대응 (Style Registry 패턴):**
  기존 Styled Components를 App Router에서 계속 사용하려면 '스타일 레지스트리(Style Registry)' 패턴을 구현해야 합니다 [4]. 이는 서버 렌더링 중에 수집된 CSS 규칙을 `useServerInsertedHTML` 훅을 통해 HTML의 `<head>`에 주입하고, 애플리케이션을 레지스트리를 제공하는 클라이언트 컴포넌트로 감싸는 3단계 접근 방식입니다 [4]. 또한 서버와 클라이언트 간 클래스 이름 불일치로 인한 수화 오류([[Hydration|Hydration]] mismatch)를 방지하기 위해 `next.config.js`에서 `styledComponents` 컴파일러 옵션을 활성화해야 합니다 [11].
* **[[styled-components v6.3+|styled-components v6.3+]] 이상의 네이티브 RSC 지원:**
  [[styled-components|styled-components]]의 최신 릴리스(v6.3.0 이상)에서는 `'use client'` 지시어 없이도 RSC 환경을 자동 감지하여 인라인 `<style>` 태그를 방출하도록 개선되었습니다 [12]. 서버 컴포넌트 환경에서는 `ThemeProvider`가 아무런 작동을 하지 않으므로(no-op), 대신 `createTheme` 유틸리티를 사용하여 CSS 사용자 지정 속성([[CSS Variables|CSS Variables]]) 기반의 테마를 구현해야 합니다 [12-15]. 추가로 인라인 스타일 태그 삽입으로 인해 자식 인덱스 선택자가 깨지는 문제는 `stylisPluginRSC`를 활용해 해결할 수 있습니다 [16, 17].
* **RSC 최적화 모범 사례:**
  동적 보간(dynamic interpolations)을 사용하여 직렬화 오버헤드를 발생시키기보다는, 정적 스타일을 선호하는 것이 좋습니다 [11, 12]. 개별 상태 변형에는 데이터 속성(`data-attributes`, 예: `&[data-size='lg']`)을 사용하면 CSS는 정적이고 캐싱 가능하게 유지하면서 JavaScript가 DOM 엘리먼트의 속성만 토글하도록 구성할 수 있습니다 [11, 12].

## 🔗 Knowledge Connections
- **Related Topics:** [[React Server Components|React Server Components]], CSS-in-JS, Tailwind CSS, [[Style Registry Pattern|Style Registry Pattern]]
- **Projects/Contexts:** [[Next.js 15|Next.js 15]], [[Styled Components v6|Styled Components v6]]
- **Contradictions/Notes:** 소스 10은 Next.js App Router 프로젝트에서 Context 기반 런타임 CSS-in-JS의 사용을 피하고 Tailwind CSS나 vanilla-extract의 사용을 권장하지만 [3, 10], 소스 3과 소스 20은 Styled Components가 v6 업데이트를 통해 Style Registry 패턴, 인라인 스타일 방출, CSS 변수(Custom Properties) 사용 등을 도입하며 RSC 및 App Router 환경과의 호환성을 적극적으로 개선하고 있음을 보여줍니다 [4, 12, 14].

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