[환경설정] Next.js App Router 기반 TailwindCSS 폰트 커스텀 설정(V4)

짜장킴·2025년 9월 17일

프로젝트

목록 보기

22/38

0. Tailwind v3 vs v4 폰트 설정 차이

Tailwind v3 (이전 방식)

설치: tailwindcss, postcss, autoprefixer 각각 설치 필요
설정 파일: tailwind.config.js, postcss.config.js 둘 다 작성해야 함
Globals.css

@tailwind base;
@tailwind components;
@tailwind utilities;

폰트 등록: tailwind.config.js → theme.extend.fontFamily에서 설정
로컬 폰트: public/fonts 직접 선언

Tailwind v4 (현재 방식)

설치: @tailwindcss/postcss 하나만 있으면 됨
설정 파일: 기본적으로 불필요, 필요할 때만 tailwind.config.ts 생성
Globals.css

@import "tailwindcss";

폰트 등록: globals.css → @theme 블록에서 --font-sans
로컬 폰트: app/fonts + next/font/local (빌드 시 해시 처리 + 최적화 자동 적용)

1. Pretendard 폰트 다운로드

Pretendard GitHub 저장소에서 원하는 woff2 파일 다운로드
Regular (400) / Medium (500) / SemiBold (600) / Bold (700)
4개면 충분

2. 프로젝트 구조

Next.js에서는 폰트를 app/fonts 안에 두는 방식 추천

src/
 └─ app/
     ├─ layout.tsx
     └─ fonts/
         └─ pretendard/
             ├─ Pretendard-Regular.woff2
             ├─ Pretendard-Medium.woff2
             ├─ Pretendard-SemiBold.woff2
             └─ Pretendard-Bold.woff2

왜 public/fonts가 아니라 app/fonts일까?

public/은 정적 파일이 그대로 /fonts/...로 노출됨

app/fonts/는 next/font/local로 번들에 포함
→ 빌드 시 /_next/static/media/... 해시 경로로 최적화

즉, app/fonts가 보안/캐싱/최적화에 유리

3. layout.tsx에서 폰트 등록

next/font/local을 이용해 Pretendard를 불러옴

// src/app/layout.tsx
import type { Metadata } from "next";
import localFont from "next/font/local";
import "./globals.css";

const pretendard = localFont({
  src: [
    { path: "./fonts/pretendard/Pretendard-Regular.woff2",  weight: "400", style: "normal" },
    { path: "./fonts/pretendard/Pretendard-Medium.woff2",   weight: "500", style: "normal" },
    { path: "./fonts/pretendard/Pretendard-SemiBold.woff2", weight: "600", style: "normal" },
    { path: "./fonts/pretendard/Pretendard-Bold.woff2",     weight: "700", style: "normal" },
  ],
  variable: "--font-pretendard",
  display: "swap", // FOUT 방지
});

export const metadata: Metadata = {
  title: "My App",
  description: "Generated by Next.js",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko" className={pretendard.variable}>
      <body className="font-sans">{children}</body>
    </html>
  );
}

4. Tailwind v4와 연결

Tailwind v4에서는 tailwind.config.js가 아니라 globals.css의 @theme에서 토큰을 관리
여기에 Pretendard를 font-sans로 매핑
layout.tsx의 className="font-sans"를 사용하면 자동으로 Pretendard가 적용

/* globals.css */
@import "tailwindcss";

@theme {
  --font-sans: var(--font-pretendard), ui-sans-serif, system-ui, -apple-system,
               "Apple SD Gothic Neo", "Noto Sans KR", "Segoe UI", "Helvetica Neue",
               Arial, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}