use client 지시어 활용

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

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

상태, effect와 이벤트 코드는 브라우저에서 실행되지만 첫 방문의 초기 HTML 생성에는 서버가 참여할 수 있습니다.

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

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

App Router의 기본 동작은 모든 컴포넌트를 서버 컴포넌트로 렌더링하는 것입니다.

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

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

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

• 컴파일러 지시어: Next.js 컴파일러와 번들러(Webpack, Turbopack)에게 해당 파일이 클라이언트 컴포넌트 그래프의 시작점임을 알립니다. 이 지시어가 없으면 파일은 서버 컴포넌트로 간주됩니다.
• 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'가 없는 경우 vs. 있는 경우

아래 다이어그램은 'use client'를 추가하기 전후로 확인해야 하는 컴파일, 번들, 하이드레이션, 디버깅 지점을 정리한 것입니다.

'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은 이미 서버에서 생성된 HTML 또는 클라이언트 컴포넌트
  return (
    <div>
      {/* 여기서 children을 조건부 렌더링하거나 다른 상호작용 추가 */}
      {children}
    </div>
  );
}

'use client'는 편리하지만 선언 위치가 넓어질수록 클라이언트 번들도 함께 커집니다.

아래 다이어그램은 Header/ToggleButton 예시를 더 일반화한 페이지 import 그래프로 보고, 지시어를 붙이기 전후로 확인할 경계, props, 번들 범위를 정리합니다.

실제 컴포넌트를 나눌 때는 기능 요구, 데이터 출처, 번들 영향, 배포 환경을 함께 보고 경계를 확정해야 합니다.

'use client' 지시어는 Next.js App Router에서 서버와 클라이언트 컴포넌트의 명확한 분리를 가능하게 하는 핵심 도구입니다.

이 지시어의 작동 원리와 최적화 전략을 이해하고 적용함으로써, 성능, 보안, 그리고 사용자 경험 모두를 향상시키는 효율적인 Next.js 애플리케이션을 구축할 수 있습니다.

use client 지시어 활용의 판단 흐름을 화면 결과, 서버 비용, 운영 신호 기준으로 다시 묶었습니다.

마지막으로 use client 지시어가 컴포넌트 실행 위치와 번들 범위에 미치는 영향을 정리합니다.