26 lines
4.2 KiB
Markdown
26 lines
4.2 KiB
Markdown
---
|
|
category: Frontend
|
|
tags: [auto-wikified, technical-documentation, frontend]
|
|
title: use client
|
|
description: "`'use client'`는 React Server Components(RSC) 패러다임에서 특정 컴포넌트를 클라이언트 컴포넌트로 명시하기 위해 사용하는 지시어(directive)이다 [1, 2]."
|
|
last_updated: 2026-05-04
|
|
---
|
|
|
|
# use client
|
|
|
|
## 📌 Brief Summary
|
|
`'use client'`는 React Server Components(RSC) 패러다임에서 특정 컴포넌트를 클라이언트 컴포넌트로 명시하기 위해 사용하는 지시어(directive)이다 [1, 2]. 이 지시어가 선언된 컴포넌트의 코드는 자바스크립트 번들에 포함되며, 서버와 클라이언트 양쪽에서 모두 렌더링 및 하이드레이션(Hydration) 과정을 거치게 된다 [2-4]. React 생태계에서 상태(State), 생명주기, 브라우저 API가 필수적으로 요구되는 상호작용 컴포넌트를 구성할 때 전략적으로 사용해야 한다 [5, 6].
|
|
|
|
## 📖 Core Content
|
|
* **클라이언트 컴포넌트로의 명시적 옵트인(Opt-in):** Next.js의 App Router와 같은 새로운 패러다임에서는 모든 컴포넌트가 기본적으로 서버 컴포넌트로 간주된다 [2]. 상태 관리, 이펙트 사용, 이벤트 핸들러 등 클라이언트 측 상호작용이 필요한 경우, 파일의 최상단에 `'use client'` 프래그마(pragma)를 추가하여 클라이언트 컴포넌트로 명시적으로 전환해야 한다 [1, 2, 5].
|
|
* **클라이언트 경계(Client Boundary)의 형성:** `'use client'` 지시어는 파일/모듈 수준에서 작동하여 "클라이언트 경계"를 형성한다 [7-9]. 해당 모듈 안에서 임포트(import)되어 렌더링되는 모든 하위 컴포넌트들은 지시어가 없더라도 암시적으로 클라이언트 컴포넌트로 변환된다 [7-9]. 따라서 상호작용이 필요한 최상단 부분에만 경계를 설정하면 되며 모든 개별 하위 파일에 지시어를 추가할 필요는 없다 [8].
|
|
* **이중 렌더링 메커니즘:** '클라이언트 컴포넌트'라는 이름과 달리, 이 컴포넌트들은 오직 클라이언트에서만 렌더링되는 것이 아니다 [4]. 실제로는 서버에서 먼저 렌더링되어 초기 HTML 뼈대를 구성하는 데 기여한 뒤, 클라이언트로 자바스크립트 코드가 다운로드되어 하이드레이션(Hydration)을 거치며 상호작용이 활성화된다 [3, 4, 10].
|
|
* **엄격한 데이터 직렬화(Serialization) 규칙:** 서버 컴포넌트와 클라이언트 컴포넌트의 경계를 가로지르는 프로프(Props)는 반드시 직렬화가 가능해야 한다 [11]. 문자열, 숫자, 객체, 배열 등은 전달이 가능하지만, 함수는 직렬화할 수 없으므로 서버 컴포넌트에서 클라이언트 컴포넌트로 이벤트 핸들러 같은 함수를 프로프로 직접 전달하려고 하면 에러가 발생한다 [11].
|
|
|
|
## ⚖️ Trade-offs & Caveats
|
|
* **자바스크립트 번들 크기 증가:** 서버 컴포넌트와 달리 `'use client'`가 선언된 컴포넌트는 렌더링 및 상호작용을 위해 브라우저로 실제 코드가 전송되어야 하므로 자바스크립트 번들 크기를 증가시킨다 [12-14].
|
|
* **Vibe Coding의 함정 및 오남용:** 아키텍처 원리에 대한 명확한 이해 없이 에러를 피하기 위해 습관적으로 모든 곳에 `'use client'`를 남발할 경우, 기존의 클라이언트 사이드 렌더링 앱과 동일하게 무거운 자바스크립트 번들이 전송된다 [6, 15]. 이는 서버 컴포넌트가 주는 '번들 크기 감소'의 혜택을 전혀 얻지 못한 채, RSC 아키텍처의 복잡성만 짊어지게 되는 안티 패턴이다 [6, 15].
|
|
* **데이터 노출에 따른 보안 위협:** 서버 컴포넌트에서 `'use client'`가 적용된 클라이언트 컴포넌트로 전달되는 모든 속성(Props)은 RSC 페이로드에 포함되어 브라우저의 네트워크 탭에 그대로 노출된다 [13, 16]. 따라서 클라이언트 렌더링에 필요한 최소한의 데이터만 전달해야 하며, 필요한 필드만 추출하지 않고 데이터베이스의 전체 행(Row) 데이터를 무심코 넘길 경우 심각한 민감 정보 유출이 발생할 수 있다 [16].
|
|
|
|
---
|
|
*Last updated: 2026-05-03* |