[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,130 +2,174 @@
|
||||
id: wiki-2026-0508-client-components
|
||||
title: Client Components
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-REINFORCE-AUTO-F09548]
|
||||
aliases: [RSC Client Components, "use client"]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
tags: [auto-reinforced]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [react, nextjs, rsc, frontend, hydration]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-03
|
||||
github_commit: "[P-Reinforce] Continuous Worker - Client Components"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: react/nextjs
|
||||
---
|
||||
|
||||
# [[Client Components|Client Components]]
|
||||
# Client Components
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
클라이언트 컴포넌트(Client Components)는 React Server Components (RSC) 패러다임에서 상태(State), 생명주기(Lifecycle), 이벤트 핸들러 및 브라우저 전용 API를 사용할 수 있는 전통적인 React 컴포넌트를 의미합니다 [1-3]. 파일 상단에 `'use client'` 지시어(directive)를 선언하여 명시적으로 정의하며, 서버 컴포넌트와 달리 자바스크립트 번들에 코드가 포함되어 브라우저에서 하이드레이션(Hydration) 과정을 거쳐 상호작용성을 제공합니다 [3-5].
|
||||
## 매 한 줄
|
||||
> **"매 interactive boundary"**. Client Components 매 React Server Components (RSC) 매 architecture 의 매 interactive half — `'use client'` directive 매 매 module-level boundary marker, 매 hydration + state + browser API 매 가능한 영역. 매 2026 현재 Next.js 13+ App Router / Remix Single Fetch / TanStack Start 의 default model.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **정의 및 실행 환경**
|
||||
명칭과 달리 클라이언트 컴포넌트는 클라이언트에서만 렌더링되는 것이 아니라, 초기에는 서버에서 렌더링된 후 클라이언트에서 다시 렌더링(하이드레이션)되는 특징을 갖습니다 [2, 6, 7]. 이는 과거 애플리케이션의 '표준(standard)' React 컴포넌트에 대한 새로운 명칭이라 볼 수 있습니다 [2].
|
||||
## 매 핵심
|
||||
|
||||
* **서버-클라이언트 경계 및 직렬화(Serialization)**
|
||||
서버 컴포넌트에서 클라이언트 컴포넌트로 전달되는 Prop은 반드시 직렬화 가능한(serializable) 값(예: 문자열, 숫자, 객체, 배열, React 요소 등)이어야 합니다 [8]. 함수는 직렬화할 수 없으므로 서버에서 클라이언트로 프로퍼티 형태의 함수 전달이 불가능합니다 [8]. 클라이언트 컴포넌트의 코드는 번들에 남아 있으며, 렌더링 시 RSC 페이로드(Payload)에는 해당 클라이언트 컴포넌트에 대한 모듈 참조(module ID, `react.client.reference`)와 직렬화된 Prop만이 포함되어 클라이언트로 전송됩니다 [9, 10].
|
||||
### 매 boundary model
|
||||
- `'use client'` 매 file-top directive — 매 module 부터 dependent tree 매 client bundle 에 포함.
|
||||
- Server Component (default) 매 server-only render — 매 zero JS shipped.
|
||||
- Client Component 매 hydrate — `useState` / `useEffect` / event handler / browser API 매 가능.
|
||||
|
||||
* **컴포넌트 중첩 및 구조화 (Interleaving)**
|
||||
클라이언트 컴포넌트는 내부에서 서버 컴포넌트를 직접 임포트(Import)하여 렌더링할 수 없습니다. 클라이언트 컴포넌트가 임포트하는 모든 하위 컴포넌트는 암시적으로 클라이언트 컴포넌트로 변환되기 때문입니다 [11, 12]. 서버 컴포넌트를 클라이언트 컴포넌트 내부에서 사용하려면, 서버 컴포넌트를 부모 영역에서 생성한 뒤 클라이언트 컴포넌트의 `children`과 같은 Prop 형태로 전달하는 중첩(Interleaving) 방식을 사용해야 합니다 [13-15]. Prop은 직렬화 가능하므로 번들러가 이 구조를 문제없이 처리할 수 있습니다 [15].
|
||||
### 매 핵심 properties
|
||||
- **Composability**: Server → Client 매 OK (props 통해), Client → Server 매 NOT (children prop slot 만 OK).
|
||||
- **Serialization**: Server → Client props 매 serializable 만 (no functions, classes, Date OK via 2026 RSC payload).
|
||||
- **Bundle**: 매 leaf client component 만 ship — 매 root 에서 'use client' 매 X.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
* **자바스크립트 번들 크기 증가:** 서버 컴포넌트는 번들에 포함되지 않아 크기를 줄여주지만, 클라이언트 컴포넌트의 코드는 여전히 사용자 브라우저로 전송되어야 하므로 너무 많은 클라이언트 컴포넌트를 사용하면 애플리케이션의 번들 사이즈가 증가합니다 [3, 16].
|
||||
* **하이드레이션 간극(Hydration Gap):** 클라이언트 컴포넌트는 서버에서 HTML 형태로 먼저 사용자에게 보일 수 있으나, 브라우저가 자바스크립트를 다운로드하고 이벤트 리스너를 연결(하이드레이션)하기 전까지는 버튼 등 UI가 사용자의 조작에 반응하지 않는 간극이 존재합니다 [17, 18].
|
||||
* **관습적 적용의 함정 (Vibe Coding Trap):** 튜토리얼을 따라 하거나 단순히 에러를 피할 목적으로 불필요한 곳까지 무분별하게 `'use client'`를 선언하는 것은 안티 패턴입니다 [19, 20]. 이는 서버 컴포넌트의 장점(번들 사이즈 감소)을 무효화하고 불필요한 아키텍처적 복잡성만 가중시키므로, 브라우저 환경이나 상태 관리 등 클라이언트 기능이 명확히 필요한 경우에만 클라이언트 컴포넌트로 지정해야 합니다 [20].
|
||||
### 매 응용
|
||||
1. Form 매 controlled input + validation.
|
||||
2. Animation / transition (Framer Motion, View Transitions API).
|
||||
3. Browser API (geolocation, clipboard, IndexedDB).
|
||||
4. Real-time (WebSocket, SSE consumer).
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
### Related Concepts
|
||||
## 💻 패턴
|
||||
|
||||
#### [관계 유형 A: 아키텍처/기반 기술]
|
||||
- [[React Server Components]]
|
||||
- 연결 이유: 클라이언트 컴포넌트는 React Server Components (RSC) 패러다임을 구성하는 반쪽이며, 이 둘은 서로 협력하여 클라이언트-서버 간의 렌더링 경계를 형성합니다 [2, 3, 21].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 번들 사이즈 최적화 원리와 데이터를 서버에서 클라이언트로 직렬화하여 전달하는 전체적인 데이터 흐름 아키텍처.
|
||||
- [[Hydration]]
|
||||
- 연결 이유: 클라이언트 컴포넌트가 브라우저에 도달하여 마침내 상호작용성을 획득하는 일련의 과정입니다 [17, 22].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: SSR(Server-Side Rendering) 환경에서 클라이언트 컴포넌트가 어떻게 기존 HTML DOM 노드에 이벤트 리스너를 부착하고 상태를 초기화하는지에 대한 내부 매커니즘 [18, 22].
|
||||
### Basic client component
|
||||
```tsx
|
||||
'use client';
|
||||
|
||||
#### [관계 유형 B: 구현/활용 도구]
|
||||
- [[use client]]
|
||||
- 연결 이유: 해당 파일과 그 파일이 임포트하는 모든 종속성이 클라이언트 컴포넌트 환경에서 실행되어야 함을 React와 번들러에 명시하는 지시어(Directive)입니다 [3-5].
|
||||
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 애플리케이션 내에서 '클라이언트 경계(Client Boundary)'가 어떻게 생성되고 파일 단위로 전파되는지에 대한 구조적 원리 [12, 23].
|
||||
import { useState } from 'react';
|
||||
|
||||
### Deeper Research Questions
|
||||
- 클라이언트 컴포넌트의 하이드레이션 병목 현상을 해결하기 위한 React 18의 'Selective Hydration'은 내부적으로 어떻게 우선순위를 결정하고 작동하는가?
|
||||
- 서버 컴포넌트를 클라이언트 컴포넌트의 `children` prop으로 전달할 때, 클라이언트의 상태(State)가 변경되어 리렌더링이 발생하면 내부의 서버 컴포넌트 결과물은 어떻게 유지되는가?
|
||||
- 대규모 React 애플리케이션에서 클라이언트 컴포넌트가 무분별하게 확장되는 것을 방지하기 위해 파일 트리를 어떻게 구조화하는 것이 가장 효과적인가?
|
||||
- React-Query나 상태 관리 라이브러리를 클라이언트 컴포넌트 최상단 계층(Providers)에 적용할 때 발생하는 성능 저하와 서버 컴포넌트 활용의 트레이드오프는 무엇인가?
|
||||
- 클라이언트 컴포넌트에서 실행되는 코드 번들의 크기를 평가하고 모니터링하기 위해 어떤 도구와 지표(Metrics)를 활용해야 하는가?
|
||||
|
||||
### Practical Application Contexts
|
||||
- **Implementation:** React로 버튼, 폼(Form), 토글(Toggle)과 같이 사용자의 직접적인 상호작용이나 상태(`useState`), 사이드 이펙트(`useEffect`)가 필요한 UI 조각을 구현할 때 상단에 `'use client'`를 선언하여 컴포넌트를 개발합니다 [1, 5].
|
||||
- **System Design:** 대규모 시스템 설계 시 전체 레이아웃과 데이터 페칭 계층은 서버 컴포넌트로 구성하고, 상태 관리가 필요한 말단의 리프 노드(Leaf Node)나 특정 상호작용 영역만 클라이언트 컴포넌트로 감싸는(Boundary) 캡슐화 전략을 적용합니다 [13, 24].
|
||||
- **Operation / Maintenance:** 코드 리뷰 및 유지보수 과정에서 정적인 텍스트만 보여주는 컴포넌트가 클라이언트 컴포넌트로 지정되지 않았는지 주기적으로 검수하여, 불필요한 자바스크립트 전송과 성능 하락을 방지합니다 [19, 20].
|
||||
- **Learning Path:** 전통적인 React의 생명주기와 상태 관리를 먼저 학습한 후, SSR과 Hydration의 한계를 파악하고, React 19 및 Next.js 앱 라우터를 통해 RSC 및 클라이언트 컴포넌트 분리 원리를 익힙니다.
|
||||
- **My Project Relevance:** 차세대 웹 프로젝트를 구축할 때, 유저 인터랙션이 잦은 장바구니/채팅 기능은 클라이언트 컴포넌트로 만들고, 제품 목록 등은 서버 컴포넌트로 구축하여 초기 렌더링 성능을 극대화하는 데 활용될 수 있습니다.
|
||||
|
||||
### Adjacent Topics
|
||||
- [[Server Actions]]
|
||||
- 확장 방향: 클라이언트 컴포넌트 내에서 발생한 이벤트를 처리하기 위해 서버 컴포넌트의 기능(데이터베이스 업데이트 등)을 브라우저에서 안전하게 호출하는 최신 패턴으로 확장하여 학습할 수 있습니다 [25-27].
|
||||
- [[Suspense]]
|
||||
- 확장 방향: 클라이언트 컴포넌트가 아직 로딩 중이거나 서버에서 데이터 스트리밍이 진행 중일 때, 사용자의 대기 시간을 부드럽게 처리하는 로딩 스켈레톤(UI) 구현 메커니즘으로 학습을 확장합니다 [28-30].
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
- Raw Source: 00_Raw/2026-05-03/Client Components.md
|
||||
---
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
export function Counter() {
|
||||
const [n, setN] = useState(0);
|
||||
return <button onClick={() => setN(n + 1)}>Count: {n}</button>;
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Server Component → Client Component (props)
|
||||
```tsx
|
||||
// page.tsx (Server)
|
||||
import { getProducts } from '@/lib/db';
|
||||
import { ProductGrid } from './ProductGrid';
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
export default async function Page() {
|
||||
const products = await getProducts(); // server fetch
|
||||
return <ProductGrid initial={products} />;
|
||||
}
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
```tsx
|
||||
// ProductGrid.tsx (Client — interactive filter)
|
||||
'use client';
|
||||
import { useState } from 'react';
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
export function ProductGrid({ initial }: { initial: Product[] }) {
|
||||
const [filter, setFilter] = useState('');
|
||||
const visible = initial.filter(p => p.name.includes(filter));
|
||||
return (
|
||||
<>
|
||||
<input value={filter} onChange={e => setFilter(e.target.value)} />
|
||||
{visible.map(p => <Card key={p.id} {...p} />)}
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Client Component 안 Server Component (children slot)
|
||||
```tsx
|
||||
// Layout.tsx (Client — needs onClick)
|
||||
'use client';
|
||||
export function Sidebar({ children }: { children: ReactNode }) {
|
||||
return <aside onClick={...}>{children}</aside>;
|
||||
}
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
// page.tsx (Server)
|
||||
import { Sidebar } from './Sidebar';
|
||||
import { ServerProfile } from './ServerProfile';
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Sidebar>
|
||||
<ServerProfile /> {/* Server component as children — OK */}
|
||||
</Sidebar>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Server Action 호출 (Client → Server mutation)
|
||||
```tsx
|
||||
'use client';
|
||||
import { createPost } from './actions'; // 'use server' file
|
||||
|
||||
export function NewPostForm() {
|
||||
return (
|
||||
<form action={createPost}>
|
||||
<input name="title" />
|
||||
<button>Submit</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Suspense + Streaming
|
||||
```tsx
|
||||
// page.tsx (Server)
|
||||
import { Suspense } from 'react';
|
||||
import { Comments } from './Comments';
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<>
|
||||
<Article />
|
||||
<Suspense fallback={<Skeleton />}>
|
||||
<Comments /> {/* streamed in */}
|
||||
</Suspense>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Static rendering, data fetching | **Server Component** (default) |
|
||||
| State / event / effect / browser API | **Client Component** |
|
||||
| SEO + interactive (form) | Server shell + Client island |
|
||||
| 매 entire page interactive (dashboard) | Mostly client, server outer layout |
|
||||
|
||||
**기본값**: 매 default Server Component — 매 boundary 를 leaf 에 push, 매 'use client' 매 minimum.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[React Server Components]] · [[Next.js App Router]]
|
||||
- 변형: [[Server Components]] · [[Server Actions]]
|
||||
- 응용: [[Hydration]] · [[Suspense]] · [[Streaming SSR]]
|
||||
- Adjacent: [[Islands Architecture]] · [[Astro]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: interactivity 매 필요한 leaf component, browser-only API, 매 form / input control.
|
||||
**언제 X**: data fetching 매 only, static content — Server Component 가 더 light.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Root layout 매 'use client'**: 매 entire app 매 client bundle — 매 RSC benefit 의 destruction.
|
||||
- **Server-only data 매 props 로 큰 객체 pass**: 매 RSC payload bloat.
|
||||
- **Client component 안 server-only import** (e.g., `fs`, `db`): 매 build error / leak risk.
|
||||
- **Server Component 안 useState**: 매 build error — 매 boundary 의 misunderstanding.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (React docs RSC 2026, Next.js 15 App Router guide).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — 'use client' boundary + composition rules + Server Action |
|
||||
|
||||
Reference in New Issue
Block a user