Antigravity Agent
f541717fe1
Processed 80+ files including Skybound playtest feedback, Monorepo strategies, and Modern Component Patterns.
3.5 KiB
3.5 KiB
Style Registry Pattern
📌 Brief Summary
스타일 레지스트리 패턴(Style Registry Pattern)은 Styled Components와 같은 런타임 CSS-in-JS 라이브러리를 React Server Components(RSC) 및 Next.js App Router 환경에 맞게 조정하기 위해 사용되는 아키텍처 패턴입니다. 서버 컴포넌트 환경에서는 React Context를 사용할 수 없어 기존의 런타임 CSS 주입 방식이 작동하지 않기 때문에, 서버 렌더링 중 CSS 규칙을 수집하는 레지스트리(Registry)를 생성하여 이를 해결합니다. 이렇게 수집된 스타일은 HTML 헤드에 직접 주입되어, 최신 서버 사이드 렌더링 패러다임 내에서도 CSS-in-JS의 기능을 유지할 수 있도록 돕는 핵심 역할을 수행합니다.
📖 Core Content
- 배경 및 문제점 (RSC와의 호환성 문제): Next.js App Router와 React Server Components(RSC) 패러다임으로의 전환은 런타임 CSS-in-JS 라이브러리의 방식에 큰 과제를 안겨주었습니다. 서버 컴포넌트는 서버에서 정적 HTML로 렌더링되며 브라우저에서 실행되지 않기 때문에, React Context에 의존하여 런타임에 스타일을 동적으로 생성하고 주입하는 기존 방식(Styled Components, Emotion 등)은 제대로 작동하지 못합니다.
- 패턴 구현을 위한 3단계 프로세스:
이러한 렌더링 간극을 메우기 위해 Next.js 15에서는 CSS-in-JS 라이브러리를 지원하기 위한 3단계 옵트인(opt-in) 프로세스로 스타일 레지스트리 패턴을 도입했습니다.
- Style Registry 생성: 서버 렌더링이 진행되는 동안 애플리케이션에서 발생하는 모든 CSS 규칙을 수집하는 레지스트리 객체를 생성합니다.
- 스타일 주입:
useServerInsertedHTML훅(hook)을 사용하여 수집된 CSS 규칙들을 HTML 문서의<head>태그 내에 주입합니다. - Provider 래핑: 이 레지스트리 컨텍스트를 제공하는 클라이언트 컴포넌트(Client Component)로 애플리케이션 전체를 감싸줍니다.
- 하이드레이션 불일치(Hydration Mismatch) 위험 및 해결책:
스타일 레지스트리 패턴을 사용하면 Styled Components를 App Router에서 기능하게 할 수 있으나, 서버와 클라이언트가 각각 렌더링될 때 서로 다른 CSS 클래스 이름을 생성할 경우 하이드레이션 불일치 문제가 발생할 위험이 있습니다. 이를 방지하기 위해 개발자는 반드시
next.config.js설정 파일에서styledComponents컴파일러 옵션을 활성화하여, 서버와 클라이언트 경계에 걸쳐 일관된 클래스 이름이 생성되도록 처리해야 합니다.
🔗 Knowledge Connections
- Related Topics: React Server Components (RSC), CSS-in-JS, Next.js App Router, Hydration Mismatch, Styled Components
- Projects/Contexts: Next.js 15, Modern Frontend Engineering Architecture
- Contradictions/Notes: 소스에 따르면 스타일 레지스트리 패턴이 Styled Components를 RSC 환경에서 작동하게 해주는 훌륭한 해결책이긴 하지만, 완전한 RSC 패러다임을 추구하는 아키텍처에서는 직렬화 오버헤드와 자바스크립트 런타임 비용(Runtime Tax)을 피하기 위해 동적 CSS-in-JS 보다는 정적 스타일(Tailwind CSS) 또는 Zero-runtime CSS-in-JS(vanilla-extract) 방식을 권장하기도 합니다.
Last updated: 2026-04-26