# [[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) 프로세스로 스타일 레지스트리 패턴을 도입했습니다.
  1. **Style Registry 생성:** 서버 렌더링이 진행되는 동안 애플리케이션에서 발생하는 모든 CSS 규칙을 수집하는 레지스트리 객체를 생성합니다.
  2. **스타일 주입:** `useServerInsertedHTML` 훅(hook)을 사용하여 수집된 CSS 규칙들을 HTML 문서의 `<head>` 태그 내에 주입합니다.
  3. **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*