Antigravity Agent
f541717fe1
Processed 80+ files including Skybound playtest feedback, Monorepo strategies, and Modern Component Patterns.
4.4 KiB
4.4 KiB
Next.js App Router Migration
📌 Brief Summary
Next.js App Router 마이그레이션은 React Server Components(RSC)를 중심으로 프론트엔드 아키텍처의 패러다임이 전환되는 과정을 의미합니다 [1]. 이는 클라이언트 측 렌더링에 의존하던 기존 방식에서 벗어나, 컴포넌트가 브라우저로 JavaScript를 전송하지 않고 서버에서 실행되도록 하여 성능과 보안을 최적화합니다 [2]. 특히 런타임 CSS-in-JS 라이브러리가 서버 컴포넌트 환경과 충돌하는 문제를 해결하기 위해, 정적 스타일링 방식이나 스타일 레지스트리(Style Registry) 패턴을 도입하는 것이 주요 마이그레이션 과제입니다 [3, 4].
📖 Core Content
- App Router와 RSC 아키텍처의 변화:
Next.js App Router는 서버 컴포넌트(Server Components)를 기본으로 사용하는 근본적인 변화를 가져왔습니다 [1, 5]. 서버 컴포넌트는 클라이언트로 JavaScript를 보내지 않으므로 번들 크기를 줄이고 성능을 향상시킵니다 [2, 6]. 상호작용이나 상태 관리가 필요한 경우에만 명시적으로
'use client'지시어를 사용하여 클라이언트 컴포넌트 경계를 설정해야 합니다 [6, 7]. - 스타일링 패러다임의 전환 (The RSC Problem): RSC는 브라우저가 아닌 서버에서 실행되므로 React Context를 사용할 수 없습니다 [3]. 이로 인해 Styled Components나 Emotion과 같이 Context 기반 런타임 테마 주입에 의존하는 CSS-in-JS 라이브러리들과 본질적인 호환성 문제(RSC Problem)가 발생했습니다 [3, 8]. 따라서 App Router 기반의 새로운 프로젝트로 마이그레이션할 때는 런타임 오버헤드가 없는 Tailwind CSS나 CSS Modules, 빌드 타임에 정적 CSS를 생성하는 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 mismatch)를 방지하기 위해next.config.js에서styledComponents컴파일러 옵션을 활성화해야 합니다 [11]. - styled-components v6.3+ 이상의 네이티브 RSC 지원:
styled-components의 최신 릴리스(v6.3.0 이상)에서는
'use client'지시어 없이도 RSC 환경을 자동 감지하여 인라인<style>태그를 방출하도록 개선되었습니다 [12]. 서버 컴포넌트 환경에서는ThemeProvider가 아무런 작동을 하지 않으므로(no-op), 대신createTheme유틸리티를 사용하여 CSS 사용자 지정 속성(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, CSS-in-JS, Tailwind CSS, Style Registry Pattern
- Projects/Contexts: Next.js 15, 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