Tailwind 설정

유틸리티 클래스는 설정 파일, CSS 지시어, Root Layout을 지나 실제 CSS가 된다

Next.js에서 Tailwind 문제는 설치 여부보다 연결 지점이 끊겼는지로 추적한다. content 스캔, @tailwind 지시어, layout.tsx import가 같은 체인에 있어야 한다.

스캔 범위 JSX, TSX, MDX가 content 배열에 포함되는지 본다.

CSS 진입점 전역 CSS에 base, components, utilities 지시어가 있는지 본다.

앱 연결 Root Layout이 전역 CSS를 한 번 가져오는지 확인한다.

파일 장부

package tailwindcss, postcss, autoprefixer

config tailwind.config.js, postcss.config.js

global css globals.css에 Tailwind 레이어를 선언한다.

root src/app/layout.tsx에서 전역 CSS를 import한다.

클래스 문자열이 시작점

01 프로젝트와 패키지

npx create-next-app@latest npm install -D tailwindcss postcss autoprefixer

새 프로젝트는 생성 질문에서 Tailwind를 선택하고, 기존 프로젝트는 의존성을 직접 추가한다.

02 설정 파일 생성

npx tailwindcss init -p tailwind.config.js postcss.config.js

Tailwind 설정과 PostCSS 진입점을 만들고, 스캔 대상 파일 구조를 맞춘다.

03 전역 CSS 연결

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

지시어가 들어간 CSS 파일을 앱의 전역 진입점으로 만든다.

04 Root Layout import

import "./globals.css"; export default function RootLayout()

Root Layout에서 전역 CSS를 가져와야 모든 페이지에 유틸리티 CSS가 적용된다.

끊긴 지점부터 찾는다

content 스캔 입력

./app/**/*.{js,ts,jsx,tsx,mdx} 같은 경로가 실제 컴포넌트 위치를 포함해야 JSX 안의 유틸리티 클래스가 최종 CSS 후보가 된다.

빠지면 클래스가 있어도 생성 CSS에 포함되지 않는다.

globals.css CSS 입력

@tailwind base, @tailwind components, @tailwind utilities 지시어가 Tailwind 레이어의 펼쳐질 위치를 정한다.

빠지면 PostCSS가 유틸리티 레이어를 주입할 자리가 없다.

layout.tsx 앱 입력

App Router에서는 Root Layout이 전역 CSS를 가져와야 페이지와 컴포넌트의 클래스가 브라우저 스타일로 이어진다.

빠지면 CSS가 생성되어도 화면에 적용되지 않는다.

스타일 미적용 원인 분리

증상	먼저 볼 곳	확인 기준	수정 방향
클래스가 전혀 먹지 않음	`layout.tsx`	전역 CSS import가 Root Layout에 있는지 확인한다.	앱 최상단에서 `globals.css`를 한 번 가져온다.
일부 파일만 스타일 없음	`content`	해당 컴포넌트 경로와 확장자가 스캔 배열에 포함되는지 본다.	app, pages, components, mdx 경로를 실제 구조에 맞춘다.
기본 스타일만 보임	`globals.css`	base, components, utilities 지시어가 모두 있는지 본다.	누락된 Tailwind 지시어를 전역 CSS 진입점에 추가한다.
클래스 문자열이 너무 길어짐	컴포넌트 경계	반복 조합이 의미 단위로 묶일 수 있는지 본다.	작은 컴포넌트, variant helper, 공통 token으로 의도를 분리한다.

핵심 연결

content 스캔, @tailwind 지시어, Root Layout import 순서가 맞아야 JSX의 유틸리티 클래스가 실제 CSS로 생성되고 화면에 적용된다.