01452025년 4월 16일

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

"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 컴포넌트이다.

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

JavaScript

// 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 훅은 사용할 수 없다.

TypeScript

// 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

최근 글