🧠 React 19 문서 메타데이터(Document Metadata) 설정 정리

React 19부터는 <title>, <meta>, <link> 같은 문서 메타데이터를 컴포넌트 내부에서 직접 선언할 수 있도록 공식 지원합니다.
이 변화로 인해 기존의 document.title 이나 react-helmet 중심의 패턴이 크게 단순화되었습니다.

1️⃣ 문서 메타데이터란?

HTML 문서의 에 위치하며 페이지의 정보, 리소스, 동작을 정의하는 요소들입니다.

React 19에서 공식적으로 지원되는 메타데이터 요소:

<title>
<meta>
<link>
<script>

2️⃣ React 19의 메타데이터 선언 방식

메타데이터도 JSX로 선언

React 19에서는 다음과 같이 컴포넌트 내부에서 그대로 작성할 수 있습니다.

function ProfilePage() {
    return (
        <>
            <title>프로필</title>

            <meta name="description" content="사용자 프로필 페이지" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />

            <link rel="canonical" href="/profile" />
            <link rel="icon" href="/favicon.ico" />

            <script src="/analytics.js" defer />

            <h1>프로필</h1>
        </>
    );
}

👉 React가 해당 요소들을 자동으로 <head>로 hoisting 합니다.

3️⃣ 동작 방식 요약

컴포넌트가 마운트되면 head에 추가
언마운트 시 자동 제거
중복 메타데이터 발생 시 → 가장 마지막에 렌더된 요소가 우선

function Layout() {
  return <title>기본 타이틀</title>;
}

function Page() {
    return <title>페이지 타이틀</title>;
}

📌 최종 <title> → 페이지 타이틀

4️⃣ `<script>` 처리 방식

<script> 또한 메타데이터와 동일한 규칙을 따릅니다.

function Analytics() {
    return (
        <script
            src="https://example.com/analytics.js"
            defer
        />
    );
}

🔹 특징

컴포넌트 마운트 → script 삽입
언마운트 → 제거
defer, async, type 등 속성 그대로 지원
SSR / Streaming 환경에서도 안전

📌 script를 useEffect로 삽입할 필요 없음

5️⃣ SSR / Streaming과의 관계

React 19의 메타데이터 시스템은 다음 환경을 기본 전제로 설계됨

✅ SSR
✅ Streaming SSR
✅ Suspense

즉, 서버 렌더링 중에도 메타데이터가 점진적으로 head에 반영

👉 CSR 전용 트릭이 아님

6️⃣ 중첩 컴포넌트 & 조건부 메타데이터

메타데이터는 JSX이기 때문에 조건부 렌더링, 상태 기반 변경이 자연스럽게 가능합니다.

function Page({ isLogin }) {
    return (
        <>
            <title>{isLogin ? '대시보드' : '로그인'}</title>
            {isLogin && <meta name="robots" content="noindex" />}
        </>
    );
}

7️⃣ 주의할 점

<head> 태그를 직접 작성하지 않음
메타데이터는 렌더 트리의 일부
사이드 이펙트 관리(useEffect) 불필요
선언 위치는 어디든 가능하지만 라우트 구조에 맞게 배치하는 게 가독성에 유리

✍️ 한 줄 정리

React 19부터 <title>, <meta>, <link>, <script>는
DOM을 조작하는 대상이 아니라, 컴포넌트가 선언하는 결과물