use client 지시어 활용

Next.js App Router에서 컴포넌트의 렌더링 환경(서버/클라이언트)을 정하는 가장 중요한 기준은 "use client" 지시어입니다.

이 문자열을 파일 맨 위에 선언하면 해당 파일과 정적 import 의존성이 클라이언트 번들 경계에 들어갑니다.

Effect와 이벤트는 브라우저에서 실행되지만 클라이언트 컴포넌트의 첫 HTML 생성에는 서버도 참여합니다. 따라서 모듈 평가·렌더 중 브라우저 전용 API를 바로 읽어도 된다는 뜻은 아닙니다.

이 절에서는 'use client'의 정확한 역할과 사용법, 그리고 내부 동작 메커니즘을 실무 관점에서 살펴봅니다.

'use client' 지시어의 역할과 중요성

App Router의 페이지와 레이아웃은 기본적으로 서버 컴포넌트입니다. 하위 모듈의 평가는 어느 경계에서 import되는지에 따라 달라집니다.

이 방식은 초기 성능, SEO, 보안 측면에서 강점이 있습니다.

다만 상호작용, 브라우저 API 접근, 클라이언트 상태 관리처럼 React의 핵심 기능 일부는 브라우저 환경에서만 가능합니다.

'use client' 지시어는 이 경계를 명확히 하여 필요한 컴포넌트만 클라이언트 번들에 포함되게 만듭니다.

• 컴파일러 지시어: Next.js 컴파일러와 번들러(Webpack, Turbopack)에게 해당 파일이 클라이언트 컴포넌트 그래프의 시작점임을 알립니다. 지시어가 없는 모듈도 클라이언트 경계에서 import되면 그 그래프에서 평가될 수 있습니다.
• JavaScript 번들 포함: 'use client'가 선언된 파일은 클라이언트 컴포넌트 그래프의 진입점이 되며, 그 파일이 임포트하는 모듈은 클라이언트 번들 경계 안으로 들어갑니다. 서버에서 렌더링한 UI를 클라이언트 컴포넌트 안에 끼워 넣어야 한다면 직접 임포트가 아니라 children이나 slot 형태로 전달합니다.
• 하이드레이션(Hydration) 트리거: 서버에서 렌더링된 HTML이 클라이언트에 도착하면, 'use client'로 표시된 컴포넌트들은 클라이언트 측 JavaScript로 하이드레이션되어 상호작용 가능한 상태가 됩니다.
• React 훅 및 브라우저 API 사용 가능: 해당 파일 내에서 useState, useEffect, window, document 등의 클라이언트 전용 기능들을 사용할 수 있게 합니다.

'use client' 사용법

'use client' 지시어는 매우 간단하게, 컴포넌트 파일의 맨 위에 위치해야 합니다.

다른 임포트 문이나 코드보다 먼저 와야 합니다.

"use client"; // 🚨 이 지시어는 항상 파일 맨 위에 와야 합니다.

import React, { useState } from 'react';

export default function InteractiveButton() {
  const [clicked, setClicked] = useState(false);

  const handleClick = () => {
    setClicked(true);
    alert('버튼이 클릭되었습니다!');
  };

  return (
    <button
      onClick={handleClick}
      style={{
        padding: '10px 20px',
        fontSize: '1em',
        backgroundColor: clicked ? '#28a745' : '#007bff',
        color: 'white',
        border: 'none',
        borderRadius: '5px',
        cursor: 'pointer',
        transition: 'background-color 0.3s'
      }}
    >
      {clicked ? '클릭됨!' : '클릭하세요'}
    </button>
  );
}

• 정확한 위치: 'use client'는 파일의 첫 번째 비-주석(non-comment) 라인이어야 합니다.
• 따옴표: 반드시 작은따옴표나 큰따옴표로 감싸야 합니다. ('use client', "use client")
• 한 번만 선언: 한 번 선언되면 해당 파일이 서버와 클라이언트 모듈 그래프의 경계가 됩니다. 이 파일에서 임포트하는 하위 모듈은 클라이언트 번들 대상이 되므로, 서버 컴포넌트로 남길 UI는 부모 서버 컴포넌트에서 렌더링해 children이나 props로 넘기는 구조를 사용합니다.

모듈 경계와 실행 시점 구분

'use client' 사용 시 고려사항 및 최적화

'use client'를 남용하면 Next.js App Router의 성능 이점을 잃을 수 있습니다.

가능한 한 최소한의 컴포넌트에만 'use client'를 선언하여 클라이언트 번들 크기를 작게 유지하는 것이 중요합니다.

// Bad (전체 헤더가 클라이언트)
"use client";
export default function Header() {
  // ... 복잡한 정적 콘텐츠와 작은 토글 버튼
  return <header>... <ToggleButton /> ...</header>;
}

// Good (토글 버튼만 클라이언트)
// components/Header.tsx (서버 컴포넌트)
import ToggleButton from './ToggleButton';
export default function Header() {
  return <header>... <ToggleButton /> ...</header>;
}

// components/ToggleButton.tsx
"use client";
export default function ToggleButton() {
  const [open, setOpen] = useState(false);
  return <button onClick={() => setOpen(!open)}>Toggle</button>;
}

import ClientWrapper from './ClientWrapper';
import ServerOnlyContent from './ServerOnlyContent';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <ClientWrapper>
      <ServerOnlyContent /> {/* 서버에서 렌더링되어 children으로 전달됨 */}
      {children} {/* 페이지 콘텐츠도 children으로 전달될 수 있음 */}
    </ClientWrapper>
  );
}

"use client";
// 이 파일은 클라이언트 컴포넌트입니다.

export default function ClientWrapper({ children }: { children: React.ReactNode }) {
  // children은 서버 렌더 결과나 다른 React 노드를 나타냅니다.
  return (
    <div>
      {/* 여기서 children을 조건부 렌더링하거나 다른 상호작용 추가 */}
      {children}
    </div>
  );
}

파일을 나누어 따라 만들기

원문의 합쳐진 발췌를 한 파일로 실행하는 대신, 같은 원리를 확인할 별도 /client-boundary 경로를 만들 수 있습니다. 기존 dashboard 파일을 바꾸지 않고 다음 세 파일을 같은 폴더에 준비하세요. Header는 서버에 두고 ToggleButton만 클라이언트 경계로 삼는 대안입니다.

import Header from './Header';

export default function ClientBoundaryPage() {
  return <main><Header /><p>본문은 서버에서 구성한 UI입니다.</p></main>;
}

import ToggleButton from './ToggleButton';

export default function Header() {
  return <header><h1>경계 확인</h1><ToggleButton /></header>;
}

"use client";

import { useState } from 'react';

export default function ToggleButton() {
  const [open, setOpen] = useState(false);
  return (
    <div>
      <button onClick={() => setOpen(value => !value)} aria-expanded={open}>
        {open ? '메뉴 닫기' : '메뉴 열기'}
      </button>
      {open && <p>이 문장의 표시는 브라우저 상태가 결정합니다.</p>}
    </div>
  );
}

페이지를 처음 열면 버튼은 메뉴 열기이고 아래 문장은 숨겨져 있습니다. 클릭하면 버튼과 문장 표시가 함께 바뀝니다. 동작 결과만으로 Header의 서버 모듈 코드가 브라우저에 들어갔다고 추정하지 않고 실제 import 경계를 확인합니다.

공유 모듈을 더하면 판단이 달라질까요?

ToggleButton이 지시어 없는 순수 문자열 formatter 모듈을 import하고, 서버 Header도 같은 모듈을 import한다고 가정하세요. formatter에 use client가 없다는 이유로 서버에서만 평가된다고 할 수 있나요? 그 formatter를 서버 전용 DB 조회로 바꾸면 같은 방식으로 브라우저에서 실행할 수 있는지도 구분합니다.

아래는 원문의 Header와 ToggleButton이 각각 어느 클라이언트 경계에 들어가는지 비교한 import 관계입니다. 화살표는 import이며 화면의 DOM 포함 관계와 구분합니다.