[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,93 +2,246 @@
|
||||
id: wiki-2026-0508-style-registry
|
||||
title: Style Registry
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [SSR Style Registry, useServerInsertedHTML, CSS-in-JS SSR]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [uncategorized]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [frontend, ssr, css-in-js, nextjs, react, app-router]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: nextjs
|
||||
---
|
||||
|
||||
# [[Style Registry|Style Registry]]
|
||||
# Style Registry
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
Style Registry는 [[Next.js App Router|Next.js App Router]] 및 React Server Components(RSC) 환경에서 Styled Components와 같은 런타임 [[CSS-in-JS|CSS-in-JS]] 라이브러리를 사용하기 위해 도입된 필수적인 렌더링 패턴입니다 [1]. 서버 렌더링 과정에서 발생하는 CSS 규칙을 수집하고, 이를 HTML 문서의 헤드(head) 부분에 안전하게 주입하는 역할을 수행합니다 [1]. 이를 통해 클라이언트 컴포넌트 래퍼를 활용하여 서버 전용 실행 환경에서 발생하는 스타일 주입의 한계를 극복합니다 [1].
|
||||
## 매 한 줄
|
||||
> **"매 SSR streaming 시 CSS-in-JS 의 styles 를 HTML 에 inject 하는 mechanism"**. Next.js 13 App Router 의 `useServerInsertedHTML` hook 도입 — 매 streaming RSC render 도중 styled-components / emotion / @mui 가 generated CSS 를 `<head>` 의 inject. 2026 zero-runtime CSS (Vanilla Extract / Panda) 의 등장 으로 registry 의 less common, but legacy SC/emotion app 의 still required.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **등장 배경 및 필요성:** [[Next.js|Next.js]]의 App Router와 React [[Server Components|Server Components]](RSC)로의 구조적 전환은 런타임 CSS-in-JS 라이브러리 구현 방식에 큰 재평가를 요구했습니다 [1]. 서버 컴포넌트가 서버에서 정적 HTML로 렌더링되기 때문에, Styled Components 같은 라이브러리는 서버 렌더링 중 기존의 런타임 스타일 주입(runtime injection) 메커니즘을 사용할 수 없게 되었습니다 [1].
|
||||
* **작동 메커니즘 (3단계 옵트인 프로세스):** 이러한 간극을 메꾸고 RSC 환경에서 CSS-in-JS를 기능하게 하기 위해 [[Next.js 15|Next.js 15]]에서는 다음과 같은 과정을 지원합니다 [1].
|
||||
1. 렌더링 중 발생하는 CSS 규칙들을 수집하기 위한 **Style Registry**를 생성합니다 [1].
|
||||
2. `useServerInsertedHTML` 훅을 사용하여 수집된 CSS 규칙들을 HTML 헤드에 주입합니다 [1].
|
||||
3. 이 레지스트리를 제공하는 클라이언트 컴포넌트(Client Component)로 전체 애플리케이션을 감싸 적용합니다 [1].
|
||||
* **하이드레이션 불일치([[Hydration|Hydration]] Mismatch) 위험과 해결:** 이 레지스트리 패턴을 활용하면 App Router 내에서 Styled Components가 기능할 수 있지만, 서버와 클라이언트가 서로 다른 클래스 이름을 생성할 경우 하이드레이션 불일치가 발생할 위험이 생깁니다 [2]. 이를 완화하기 위해서는 `next.config.js` 파일에서 `styledComponents` 컴파일러 옵션을 필수적으로 활성화하여 서버-클라이언트 경계 전반에 걸쳐 일관된 클래스 이름 생성을 보장해야 합니다 [2].
|
||||
## 매 핵심
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[React Server Components|React Server Components]], CSS-in-JS, Styled Components, [[Next.js App Router|Next.js App Router]], Hydration Mismatch
|
||||
- **Projects/Contexts:** Modern [[Frontend|Frontend]] Engineering, Next.js 15 Migration
|
||||
- **Contradictions/Notes:** 소스 내 직접적인 모순점은 없으나, Style Registry 패턴 자체만으로는 서버와 클라이언트 간 클래스명 불일치라는 부작용을 막을 수 없으므로 `next.config.js` 컴파일러 설정을 통한 보완이 반드시 병행되어야 합니다 [2].
|
||||
### 매 Why needed
|
||||
- **CSS-in-JS = runtime styles**: rules generated when component renders.
|
||||
- **SSR**: server renders HTML; client hydrates. Without registry → FOUC (flash of unstyled content) + hydration mismatch.
|
||||
- **Streaming SSR**: HTML chunks sent progressively. Styles must inject as components render, not at end.
|
||||
- **App Router**: `useServerInsertedHTML` provides hook into Suspense boundary stream.
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26*
|
||||
### 매 Mechanism
|
||||
1. Server: collect styles into sheet during render (per request).
|
||||
2. Server: insert `<style>` tags into HTML stream via `useServerInsertedHTML`.
|
||||
3. Client: hydrate — runtime takes over, no re-render needed.
|
||||
4. Concurrency: per-request sheet (no global state pollution).
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 매 응용
|
||||
1. styled-components in Next.js App Router.
|
||||
2. Emotion in Next.js App Router.
|
||||
3. @mui v5+ in Next.js.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
### styled-components Registry
|
||||
```typescript
|
||||
// app/lib/registry.tsx
|
||||
'use client';
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
import React, { useState } from 'react';
|
||||
import { useServerInsertedHTML } from 'next/navigation';
|
||||
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
export default function StyledComponentsRegistry({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet());
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
useServerInsertedHTML(() => {
|
||||
const styles = styledComponentsStyleSheet.getStyleElement();
|
||||
styledComponentsStyleSheet.instance.clearTag();
|
||||
return <>{styles}</>;
|
||||
});
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
if (typeof window !== 'undefined') return <>{children}</>;
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
|
||||
- **과거 데이터와의 충돌:** 없음
|
||||
- **정책 변화:** 없음
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
return (
|
||||
<StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
|
||||
{children}
|
||||
</StyleSheetManager>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Apply in root layout
|
||||
```typescript
|
||||
// app/layout.tsx
|
||||
import StyledComponentsRegistry from './lib/registry';
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<StyledComponentsRegistry>{children}</StyledComponentsRegistry>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Emotion Registry
|
||||
```typescript
|
||||
// app/lib/emotion-registry.tsx
|
||||
'use client';
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
import createCache from '@emotion/cache';
|
||||
import { CacheProvider } from '@emotion/react';
|
||||
import { useServerInsertedHTML } from 'next/navigation';
|
||||
import { useState } from 'react';
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
export default function EmotionRegistry({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
const [{ cache, flush }] = useState(() => {
|
||||
const cache = createCache({ key: 'css' });
|
||||
cache.compat = true;
|
||||
const prevInsert = cache.insert;
|
||||
let inserted: string[] = [];
|
||||
cache.insert = (...args) => {
|
||||
const serialized = args[1];
|
||||
if (cache.inserted[serialized.name] === undefined) {
|
||||
inserted.push(serialized.name);
|
||||
}
|
||||
return prevInsert(...args);
|
||||
};
|
||||
const flush = () => {
|
||||
const prev = inserted;
|
||||
inserted = [];
|
||||
return prev;
|
||||
};
|
||||
return { cache, flush };
|
||||
});
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
useServerInsertedHTML(() => {
|
||||
const names = flush();
|
||||
if (names.length === 0) return null;
|
||||
let styles = '';
|
||||
for (const name of names) {
|
||||
styles += cache.inserted[name];
|
||||
}
|
||||
return (
|
||||
<style
|
||||
data-emotion={`${cache.key} ${names.join(' ')}`}
|
||||
dangerouslySetInnerHTML={{ __html: styles }}
|
||||
/>
|
||||
);
|
||||
});
|
||||
|
||||
return <CacheProvider value={cache}>{children}</CacheProvider>;
|
||||
}
|
||||
```
|
||||
|
||||
### @mui Registry
|
||||
```typescript
|
||||
// app/lib/mui-registry.tsx
|
||||
'use client';
|
||||
|
||||
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
|
||||
import { ThemeProvider } from '@mui/material/styles';
|
||||
import { theme } from './theme';
|
||||
|
||||
export default function MuiRegistry({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
return (
|
||||
<AppRouterCacheProvider options={{ enableCssLayer: true }}>
|
||||
<ThemeProvider theme={theme}>{children}</ThemeProvider>
|
||||
</AppRouterCacheProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Pages Router (legacy) — _document.tsx
|
||||
```typescript
|
||||
// pages/_document.tsx — Pages Router uses different mechanism
|
||||
import Document, { DocumentContext } from 'next/document';
|
||||
import { ServerStyleSheet } from 'styled-components';
|
||||
|
||||
export default class MyDocument extends Document {
|
||||
static async getInitialProps(ctx: DocumentContext) {
|
||||
const sheet = new ServerStyleSheet();
|
||||
const originalRenderPage = ctx.renderPage;
|
||||
try {
|
||||
ctx.renderPage = () =>
|
||||
originalRenderPage({
|
||||
enhanceApp: App => props =>
|
||||
sheet.collectStyles(<App {...props} />),
|
||||
});
|
||||
const initialProps = await Document.getInitialProps(ctx);
|
||||
return {
|
||||
...initialProps,
|
||||
styles: [initialProps.styles, sheet.getStyleElement()],
|
||||
};
|
||||
} finally {
|
||||
sheet.seal();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Verifying SSR works
|
||||
```typescript
|
||||
// 1. View source (Cmd+U) — should see <style> tags with rules
|
||||
// 2. Disable JS in DevTools — page should still be styled
|
||||
// 3. Check Network tab — no FOUC during page transition
|
||||
// 4. React DevTools — no hydration mismatch warnings
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Greenfield 2026 Next.js | Tailwind / Vanilla Extract — no registry needed |
|
||||
| Existing styled-components migration | Add StyledComponentsRegistry |
|
||||
| Emotion-based codebase | EmotionRegistry pattern |
|
||||
| @mui v5+ | AppRouterCacheProvider (built-in) |
|
||||
| Pages Router legacy | _document.tsx + sheet collection |
|
||||
|
||||
**기본값**: greenfield → zero-runtime CSS (no registry). Existing CSS-in-JS → use library-recommended registry pattern.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[CSS in JS]] · [[SSR]] · [[Next.js App Router]]
|
||||
- 변형: [[useServerInsertedHTML]] · [[ServerStyleSheet]] · [[Emotion Cache]]
|
||||
- 응용: [[Styled Components v6]] · [[Emotion]] · [[Material UI]]
|
||||
- Adjacent: [[Streaming SSR]] · [[React Server Components]] · [[Hydration]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: SSR setup for CSS-in-JS, Next.js App Router migration from Pages, debugging FOUC / hydration mismatch.
|
||||
**언제 X**: Tailwind / CSS Modules / Vanilla Extract — these are zero-runtime, no registry needed.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **No registry → FOUC**: styled-components SSR without registry shows unstyled HTML on first paint.
|
||||
- **Global sheet (not per-request)**: cross-request style pollution / memory leak.
|
||||
- **`'use client'` on registry but rendered at top level**: marks entire tree as client — kills RSC benefit. Wrap deeply.
|
||||
- **Forgetting `clearTag()`**: duplicate styles inserted on each chunk.
|
||||
- **Mixing registries**: emotion + styled-components → two style systems, double bundle, conflicts.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Next.js docs `app/building-your-application/styling`, styled-components Next.js example, Emotion + Next.js guide).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — full canonical (registry mechanism + SC/Emotion/MUI patterns + Pages Router fallback) |
|
||||
|
||||
Reference in New Issue
Block a user