💻 개발/🎩 Next.js

[Next.js] _app.tsx와 _document.tsx 완전 이해하기

pangil_kim 2025. 4. 16. 04:04
728x90

"Next.js에서 컴포넌트는 익숙한데... _app.tsx는 뭐고 _document.tsx는 또 뭐지?"

처음에는 괜히 프로젝트에 붙어 있는 듯한 느낌이지만, 이 두 파일을 이해하면 Next.js의 전체 앱 구조가 눈에 들어온다.

 

 

 

🏠 건물로 비유해보자

 

Next.js 앱을 하나의 건물이라고 생각해보자.

  • _document.tsx는 건물의 설계도와 구조물이다. (콘크리트, 창문, 외벽 등)
  • _app.tsx는 건물 내부의 인테리어다. (벽지, 가구, 조명, 공기청정기 등)

즉, _document.tsx는 HTML 구조 자체를 커스터마이징하고,

_app.tsx는 그 안에서 React 페이지들이 어떻게 렌더링될지를 설정한다.

 

 

 

_app.tsx – 전체 앱의 진입점

 

_app.tsx는 Next.js에서 모든 페이지가 렌더링되기 전에 공통으로 거쳐 가는 React 컴포넌트이다.

 

예를 들어, 모든 페이지에 같은 레이아웃이나 스타일을 적용하고 싶을 때 여기서 처리한다.

// pages/_app.tsx

import "@/styles/globals.css";
import Layout from "@/components/Layout";

export default function MyApp({ Component, pageProps }) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  );
}
  • Component는 현재 라우팅된 페이지
  • pageProps는 그 페이지에서 넘겨받은 props

 

그렇다면, 명확하게 언제 쓰는가?

  • 전역 스타일 import (globals.css)
  • 공통 레이아웃 적용 (Header, Footer)
  • 상태 관리 Provider 감싸기 (예: Recoil, Zustand, Redux)
  • 페이지 전환 로딩 처리

 

 

 

_document.tsx – HTML 문서 구조를 커스터마이징하는 곳

 

_document.tsx는 말 그대로 HTML 문서의 기본 구조를 설정하는 파일이다.

 

이건 React가 아니라 Next.js의 서버 사이드 렌더링 단계에서만 작동하기 때문에, useEffect 같은 React 훅은 사용할 수 없다.

// pages/_document.tsx

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="ko">
      <Head>
        <link rel="preconnect" href="https://fonts.googleapis.com" />
        <meta name="theme-color" content="#ffffff" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}


그렇다면, 명확하게 언제 쓰는가?

  • <html lang="ko">처럼 HTML 태그 속성 지정
  • Google Fonts, meta 태그 설정
  • <body class=""> 초기값 설정
  • 웹폰트 프리로드 최적화
  • SEO/OG 태그 선처리

CSS보다 더 근본적인 곳에서 앱을 커스터마이징하고 싶다면,

_document.tsx가 그 시작점이다.

 

 

 

정리: React와 뭐가 다른가?
구분
 React Next.js
앱 진입점 index.tsx 혹은 App.js _app.tsx
HTML 문서 구조 설정 직접 접근 불가능 _document.tsx에서 접근 가능
공통 레이아웃 수동 구현 _app.tsx에서 자동 적용 가능
서버사이드 렌더링용 HTML 조작 불가 _document.tsx에서 가능

 

 

 

 

핵심 요약
파일
 역할 자주 쓰이는 기능
_app.tsx 전체 앱을 감싸는 React 컴포넌트 전역 스타일, 공통 레이아웃, 상태 관리 Provider
_document.tsx HTML 문서 구조 설정 <html>, <body>, <meta>, 폰트, SEO 설정 등

 

 

 

✨ 마무리하며

Next.js에서 _app.tsx와 _document.tsx는 말 그대로 앱의 뼈대이다.

이 구조를 제대로 이해하면, 프로젝트의 확장성과 유지보수성이 훨씬 높아진다.

 

📢 기억하자.

_app.tsx는 React 컴포넌트의 시작점,

_document.tsx는 HTML 문서의 시작점이다.

 

🚨잠깐!!🚨

이번 글에서 짚어본 내용은 pages 라우팅을 사용했을 때 사용한 방식이다.

그렇다면, app 라우팅을 사용한 방식에서는 어떻게 앱의 뼈대가 구성될까?

이 부분에 대해서는 아래 글을 참고하자!
https://pangil-log.tistory.com/282
 

[Next.js] pages는 이제 안녕? App Router가 가져온 구조 혁신

“Next.js를 배우고 있는데… /app 디렉토리?_app.tsx, _document.tsx는 이제 안 쓰는 건가요?” Next.js 13부터 등장한 App Router는 단순한 디렉토리 변경이 아니다. 파일 기반 라우팅 → 컴포넌트 기반 아키텍

pangil-log.tistory.com

 

728x90