02792025년 8월 16일

[Next.js] Next.js 15와 Tailwind CSS v4: 더 이상 tailwind.config.ts는 필요 없다

들어가며

Next.js 15와 Tailwind CSS v4가 나오면서 가장 큰 변화 중 하나는 설정 방식이다.

이제는 더 이상 tailwind.config.ts 파일이 필수적이지 않고, CSS-first 접근 방식으로 globals.css에서 직접 테마를 정의할 수 있다.

즉, 테마와 디자인 토큰을 **CSS 변수(@theme)**로 선언하고, Tailwind가 이를 기반으로 유틸리티 클래스를 자동으로 생성한다.

기존(v3)과 새로운(v4) 방식 비교

1) v3 (기존 방식)

code

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: '#7adaa5',
      },
      spacing: {
        128: '32rem',
      },
    },
  },
};

2) v4 (새로운 방식)

CSS

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

@theme inline {
  --color-brand: #7adaa5;
  --spacing-128: 32rem;
}

? 이제는 CSS 변수만 선언하면, Tailwind가 자동으로 text-brand, bg-brand, p-128, m-128 같은 클래스를 만들어준다.

파일 분리 구조

규모가 커질수록 색상, 폰트, spacing 등을 별도 파일로 분리하는 게 유리하다.

예를 들어:

code

src/app/globals.css
src/app/styles/colors.css
src/app/styles/fonts.css
src/app/styles/spacing.css

1) colors.css

CSS

:root {
  --brand: #7adaa5;
  --accent: #239ba7;
}

@theme inline {
  --color-brand: var(--brand);
  --color-accent: var(--accent);
}

2) fonts.css

CSS

:root {
  --geist-sans: Inter, sans-serif;
  --geist-mono: Fira Code, monospace;
}

@theme inline {
  --font-sans: var(--geist-sans);
  --font-mono: var(--geist-mono);
}

3) globals.css

CSS

@import "tailwindcss";
@import "./styles/colors.css";
@import "./styles/fonts.css";

:root {
  --background: #ffffff;
  --foreground: #171717;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

Tailwind v4 네이밍 규칙

@theme 안에서 어떤 이름으로 CSS 변수를 선언하느냐에 따라 Tailwind가 인식하는 유틸리티가 달라진다.

변수명 패턴	생성되는 유틸리티 예시
--color-*	text-, bg-, border-, shadow-
--spacing-*	p-, m-, gap-, space-x-
--font-*	font-*
--text-*	text-* (폰트 크기)
--breakpoint-*	sm:, md:, lg: 등 반응형 prefix
--radius-*	rounded-*
--shadow-*	shadow-*
--z-*	z-*
--opacity-*	opacity-*

? 예를 들어,

code

@theme inline {
  --color-brand: #7adaa5;
  --spacing-128: 32rem;
}

→ bg-brand, text-brand, p-128, m-128 자동 생성

실제 사용 예시

JavaScript

export default function Home() {
  return (
    <main>
      <h1 className="text-brand text-4xl font-sans">Hello Tailwind v4</h1>
      <p className="bg-accent text-white p-128">Next.js 15 + Tailwind v4</p>
    </main>
  );
}

마무리

Next.js 15 + Tailwind CSS v4 환경에서는 이제

tailwind.config.ts 없이
globals.css 혹은 분리된 CSS 파일에서
@theme 변수를 선언하여디자인 토큰과 유틸리티 클래스를 관리할 수 있다.

작은 프로젝트라면 globals.css 하나로 충분하고, 큰 프로젝트라면 colors.css, fonts.css 등으로 분리해서 관리하는 게 더 깔끔하다.

이제는 JS 설정이 아닌 CSS-first 방식이 Tailwind의 새로운 표준이다.

최근 글