# [[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의 ``에 주입하고, 애플리케이션을 레지스트리를 제공하는 클라이언트 컴포넌트로 감싸는 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 환경을 자동 감지하여 인라인 `