Next.js 16 App Router 프로젝트에 Tailwind CSS 4 초기 설정 및 사용 방법

Next.js 16 App Router 프로젝트에 Tailwind CSS 4(프리뷰 버전)를 통합하는 과정은 몇 가지 간단한 설정 단계를 거칩니다. 이 가이드는 Tailwind CSS 4의 최신 기능을 활용하기 위해 필요한 설치, 설정 파일 구성, 그리고 전역 CSS 통합 방법을 안내합니다.

Tailwind CSS 4 및 의존성 설치

가장 먼저 프로젝트에 Tailwind CSS 4와 그 의존성인 PostCSS, Autoprefixer를 설치해야 합니다. Tailwind CSS 4는 현재 프리뷰 버전이므로 @next 태그를 사용하여 설치합니다. 프로젝트에서 pnpm을 사용하고 있으므로 pnpm 명령어를 기준으로 설명합니다.

pnpm add -D tailwindcss@next postcss autoprefixer

tailwindcss@next: Tailwind CSS 4의 프리뷰 버전을 설치합니다.
postcss: CSS를 변환하는 도구입니다. Tailwind CSS는 PostCSS 플러그인으로 동작합니다.
autoprefixer: PostCSS 플러그인으로, CSS에 자동으로 벤더 프리픽스(예: -webkit-)를 추가하여 브라우저 호환성을 높여줍니다.

Tailwind CSS 설정 파일 생성 및 구성

설치가 완료되면, Tailwind CSS의 설정 파일을 생성해야 합니다. TypeScript 프로젝트이므로 tailwind.config.ts 파일을 생성합니다. 이 파일은 Tailwind CSS가 스캔할 파일 경로와 커스텀 테마 등을 정의하는 데 사용됩니다.

pnpm tailwindcss init -t ts

이 명령어를 실행하면 프로젝트 루트에 tailwind.config.ts 파일이 생성됩니다. 생성된 파일을 열어 content 배열에 Tailwind CSS 클래스를 사용하는 모든 파일의 경로를 추가해야 합니다. App Router 구조에서는 src/app 및 src/components 디렉토리 내의 파일들을 포함하는 것이 일반적입니다.

// tailwind.config.ts
import type { Config } from 'tailwindcss';

const config: Config = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}', // Pages Router를 사용한다면 필요, App Router만 사용시 제외 가능
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

export default config;

PostCSS 설정 파일 구성 (`postcss.config.mjs`)

Next.js는 PostCSS를 사용하여 CSS를 처리합니다. 따라서 Tailwind CSS와 Autoprefixer가 PostCSS를 통해 작동하도록 postcss.config.mjs 파일을 설정해야 합니다. 이 파일은 프로젝트 루트에 생성합니다.

// postcss.config.mjs
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

tailwindcss: PostCSS에 Tailwind CSS 플러그인을 활성화합니다.
autoprefixer: PostCSS에 Autoprefixer 플러그인을 활성화합니다.

전역 CSS에 Tailwind 지시문 추가

이제 Tailwind CSS의 기본 스타일, 컴포넌트, 유틸리티 클래스를 프로젝트에 주입해야 합니다. 이를 위해 Next.js App Router의 전역 CSS 파일인 src/app/globals.css에 Tailwind CSS 지시문을 추가합니다.

/* src/app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 여기에 사용자 정의 CSS를 추가할 수 있습니다 */

src/app/layout.tsx 파일에서 globals.css를 임포트하고 있는지 확인하세요.

// src/app/layout.tsx
import type { Metadata } from 'next';
import './globals.css'; // Tailwind CSS가 포함된 전역 CSS 임포트

export const metadata: Metadata = {
  title: 'My Next.js App',
  description: 'Generated by create next app',
};

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

Tailwind CSS 클래스 사용 및 동작 확인

모든 설정이 완료되었으므로, 이제 Next.js 컴포넌트에서 Tailwind CSS 클래스를 사용하여 스타일을 적용할 수 있습니다. 프로젝트를 개발 모드로 실행하여 변경 사항을 확인합니다.

pnpm dev

예를 들어, src/app/page.tsx 파일에서 다음과 같이 Tailwind CSS 클래스를 사용할 수 있습니다.

// src/app/page.tsx
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24 bg-gray-100">
      <h1 className="text-4xl font-bold text-blue-600 mb-8">Hello, Tailwind CSS 4!</h1>
      <p className="text-lg text-gray-700">Next.js 16 App Router와 함께 성공적으로 설정되었습니다.</p>
      <button className="mt-4 px-6 py-3 bg-green-500 text-white rounded-lg shadow-md hover:bg-green-600 transition-colors">
        버튼입니다
      </button>
    </main>
  );
}

브라우저에서 페이지를 확인하면, Tailwind CSS 클래스가 정상적으로 적용되어 스타일이 나타나는 것을 볼 수 있습니다.

흔히 하는 실수 및 주의점