Antigravity Agent
4.3 KiB
4.3 KiB
Client Components
📌 Brief Summary
클라이언트 컴포넌트(Client Components)는 모던 React 아키텍처(예: Next.js 15 App Router)에서 'use client' 지시어로 정의되며 전통적인 React 컴포넌트처럼 동작하는 UI 요소이다 [1]. 서버 컴포넌트와 달리 클라이언트 측 자바스크립트를 실행하므로 상태(State) 관리, 이벤트 핸들러 등 상호작용이 필요하거나 브라우저 API를 사용해야 할 때 필수적으로 적용된다 [1, 2]. 확장 가능한 프론트엔드 환경에서는 자바스크립트 번들 크기를 최소화하고 성능을 극대화하기 위해 클라이언트 컴포넌트를 작고 기능적으로 집중된 형태로 유지하는 것이 핵심 원칙이다 [2, 3].
📖 Core Content
- 경계 설정 및 하이드레이션(Hydration): 클라이언트 컴포넌트는 최상단에
'use client'지시어를 선언하여 클라이언트 측 자바스크립트가 시작되는 경계를 명확히 표시한다 [1]. 서버가 렌더링한 정적 HTML에 React가 이벤트 리스너와 상태를 연결하여 상호작용을 가능하게 만드는 과정인 하이드레이션(Hydration)은 Next.js 15 기준으로 오직 클라이언트 컴포넌트에서만 발생한다 [4]. - 컴포넌트 합성 패턴(Composition Patterns): 재사용 가능하고 확장성 있는 UI를 구축하기 위해 다양한 합성 패턴이 사용된다. 서버 컴포넌트가 클라이언트 컴포넌트를 하위 요소로 렌더링하거나, 반대로 서버 컴포넌트를 클라이언트 컴포넌트의 자식(children)이나 props로 전달하여 자식 요소가 서버 컴포넌트로서의 특성을 유지하게 할 수 있다 [1, 4]. 또한 클라이언트 측 상태를 앱 전반에 공유하기 위해 Context Provider 패턴을 사용하기도 한다 [4].
- 확장 가능한 프론트엔드를 위한 모범 사례:
- 기본적으로 서버 컴포넌트를 사용하고 상호작용이 필요한 구역만 클라이언트 컴포넌트로 분리하여 작게 유지해야 한다 [2, 3].
- 레이아웃 등 최상단 요소에 불필요하게
'use client'를 남용하면 하위의 모든 라우트가 클라이언트 측 컴포넌트로 강제 전환되므로 주의해야 한다 [3]. - 데이터 패칭은 가급적 서버 측에서 수행하여 클라이언트 번들 크기를 줄이고 보안을 유지해야 한다 [3].
- 함수, 날짜, 클래스 인스턴스 등 직렬화할 수 없는(non-serializable) props를 서버 컴포넌트에서 클라이언트 컴포넌트로 넘겨서는 안 된다 [5].
- 스타일링 파라다임 및 테마 적용(CSS-in-JS): Next.js App Router 아키텍처에서 styled-components와 같은 런타임 CSS-in-JS 라이브러리를 사용하려면, 렌더링 중 CSS 규칙을 수집하기 위한 '스타일 레지스트리(Style Registry)'를 구성하고 이를 클라이언트 컴포넌트로 래핑해야 한다 [6]. 더 나아가, React Context 없이도 클라이언트 컴포넌트와 서버 컴포넌트 모두에서 테마가 작동하도록 CSS 사용자 지정 속성(CSS custom properties)을 기반으로 한
createTheme등의 기능이 도입되어 렌더링 컨텍스트의 한계를 극복하고 있다 [7].
🔗 Knowledge Connections
- Related Topics: Server Components, Hydration, CSS-in-JS, React Context
- Projects/Contexts: Next.js App Router, styled-components
- Contradictions/Notes: 전통적인 런타임 CSS-in-JS 라이브러리(styled-components, Emotion)는 내부적으로 React Context에 의존하기 때문에 서버 컴포넌트에서는 작동하지 않고 클라이언트 컴포넌트 래핑이 필요하지만, 대규모 프로젝트의 성능(Core Web Vitals) 향상과 Next.js App Router와의 완벽한 호환을 위해서는 런타임 비용이 없는 Tailwind CSS, CSS Modules 또는 vanilla-extract 등의 정적 CSS 생성 도구로의 전환이 2025년 기준 더욱 강력히 권장되고 있다 [6, 8-11].
Last updated: 2026-04-26