노트

'use client'와 클라이언트 경계

Client Components and the use client Directive

프런트엔드#react#nextjs · 연결된 개념 15개

쉽게 말하면

'use client'는 여기서부터 브라우저로 보낸다고 세운 국경 표지판이에요. 표지판을 넘은 파일과 그 파일이 import한 건 다 브라우저로 가니, 눌러야 하는 곳에만 작게 세우면 보내는 JS가 줄어요.

비유가 깨지는 곳 국경 기준은 화면 속 위치가 아니라 누가 import했느냐예요. 그래서 클라이언트 Provider 안에 children으로 넣은 서버 컴포넌트는 서버에 남고, 클라이언트 컴포넌트도 첫 요청에선 서버에서 HTML로 미리 렌더돼요.

'use client'는 파일 맨 위에 적어 "여기서부터 클라이언트 번들에 들어간다"는 경계를 선언하는 지시어(Directive)다. 경계 파일과 그 파일이 import하는 모듈은 모두 클라이언트 컴포넌트가 된다. state, Effect, 이벤트 핸들러, 브라우저 API(Application Programming Interface)가 필요한 곳에 쓴다.

  • 경계에만 한 번 쓴다. 아래로 import되는 컴포넌트에 일일이 붙일 필요가 없다
  • 이름과 달리 클라이언트 컴포넌트도 첫 요청에서는 서버에서 HTML(HyperText Markup Language)로 미리 렌더되고, 브라우저에서 하이드레이션된다
  • 클라이언트 컴포넌트는 서버 컴포넌트를 import할 수 없다. 클라이언트에서 다시 렌더될 때 서버 코드를 실행할 수 없기 때문이다. 하지만 children이나 prop으로 서버 컴포넌트를 받는 것은 된다. 서버에서 이미 렌더된 결과가 들어가기 때문이다
// ThemeProvider는 'use client'지만, 안쪽 Page는 서버 컴포넌트로 남는다
<ThemeProvider>
  <Page />
</ThemeProvider>

그래서 테마·인증 같은 Provider를 최상단에 둬도 앱 전체가 클라이언트로 바뀌지 않는다. 부모·자식 관계가 아니라 누가 import했는가가 기준이다

서버 쪽은 React 서버 컴포넌트(RSC), 서버 함수를 클라이언트에서 부르는 지시어는 'use server'(서버 함수와 서버 액션).

연결된 개념

이 노트를 가리키는 문서

뜻이 가까운 노트

  • loading 경계와 레이아웃 끌어올리기

    Next.js App Router에서 loading.tsx는 같은 세그먼트의 page와 그 아래(하위 layout 포함)를 suspense로 감싸지만, **같은 세그먼트의 layout은 감싸지 않는다**. 그래서 데이터를 기다릴 필요가 없는 공통 UI(탭바, 필터 헤더)를 page에서 layout으로 끌어올리면 스켈레톤에 덮이지 않고 처음부터 실제 모습으로 보인다.

  • 서버 렌더에서 훅이 하는 일

    서버 렌더(Server-Side Rendering, SSR)에서도 컴포넌트 함수는 실제로 호출되고, 그 안의 훅도 호출은 된다. 다만 서버에는 커밋(DOM 반영)이 없어서, 렌더 중 동기적으로 값을 계산하는 훅만 일하고 커밋 뒤에 도는 훅은 아무것도 하지 않는다. "이 훅은 클라이언트에서만 동작한다"는 말은 대개 "Effect 안의 일은 클라이언트에서만 일어난다"는 뜻이다.

  • CSS-in-JS와 빌드 타임 CSS

    JS(JavaScript) 안에서 스타일을 정의하고, 렌더링할 때 라이브러리가 클래스를 만들어 style 태그로 주입하는 방식. styled-components와 Emotion이 대표다. React 18 이후 서버 컴포넌트(React Server Components)·스트리밍 SSR(Streaming Server-Side Rendering)이 자리 잡으면서 런타임에 CSS를 만드는 방식은 줄고, 빌드할 때 CSS를 뽑는 방식이 늘었다(2026 기준).

  • 브라우저 렌더링 파이프라인

    브라우저가 받은 HTML·CSS·JS를 화면의 픽셀로 바꾸는 순서. 처음 로드할 때도, 이후 무언가 바뀔 때도 같은 단계를 거친다. 바뀐 내용에 따라 어느 단계부터 다시 시작하는지만 다르다.

  • Suspense

    Suspense는 아직 준비되지 않은 하위 트리의 렌더를 잠시 보류(suspend)하고, 그동안 가장 가까운 경계의 fallback을 보여 주는 React의 비동기 렌더링 메커니즘이다. 로딩 상태를 컴포넌트마다 들고 있지 않고 경계에 위임한다.

보기 옵션