Tailwind CSS 4.0 설정 문제 해결하기: PostCSS 플러그인 오류부터 Vite 설정까지

안녕하세요 웹 YB 신지수입니다 !

이번 3주차 과제에서 Tailwind CSS를 사용하려 했지만, 버전 4.0에서 발생한 PostCSS 플러그인 오류로 인해 어려움을 겪었습니다. 이 글에서는 이 문제의 원인과 해결 방법을 공유하려고 합니다 🤓

먼저 Tailwind CSS가 무엇인지, 그리고 어떤 장점이 있는지 간단히 소개한 후 문제 해결 과정을 설명하겠습니다 !

🎨 Tailwind CSS

Tailwind CSS란 ?

Tailwind CSS는 유틸리티 기반 CSS 프레임워크로, 미리 정의된 클래스들을 HTML 요소에 직접 적용하여 스타일링하는 방식입니다. 기존의 Bootstrap이나 Foundation과 같은 프레임워크가 미리 디자인된 컴포넌트를 제공하는 것과 달리, Tailwind는 작은 단위의 유틸리티 클래스들을 조합해 자유롭게 디자인을 구성할 수 있게 해줍니다.

<!-- 기존 CSS 방식 -->
<div class="card">
  <h2 class="card-title">제목</h2>
  <p class="card-text">내용</p>
</div>

<!-- Tailwind CSS 방식 -->
<div class="rounded-lg shadow-md p-6 bg-white">
  <h2 class="text-xl font-bold mb-2 text-gray-800">제목</h2>
  <p class="text-gray-600">내용</p>
</div>

Tailwind의 유틸리티 클래스들은 일종의 "CSS 단축키"처럼 작동합니다. p-6은 padding: 1.5rem을, text-xl은 font-size: 1.25rem을 의미합니다. 이렇게 직관적인 클래스 이름을 통해 CSS를 작성하는 시간을 절약하고, 일관된 디자인 시스템을 유지할 수 있습니다.

Tailwind CSS의 장점

1. CSS 작성 시간 단축
미리 정의된 유틸리티 클래스를 사용하면 별도의 CSS 파일을 작성하는 시간을 크게 줄일 수 있습니다. 복잡한 선택자를 생각하거나 클래스 이름을 고민할 필요 없이, HTML 내에서 바로 스타일링이 가능합니다.

<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
  버튼
</button>

2. 모듈화된 CSS로 코드 중복 감소 및 유지보수 용이

Tailwind CSS는 미리 정의된 유틸리티 클래스들을 재사용하므로, 중복된 CSS 코드를 작성할 필요가 없습니다. 이는 코드 베이스의 크기를 줄이고 유지 보수를 용이하게 합니다. 또한 스타일 변경이 필요할 때도 HTML 파일 내에서 클래스만 수정하면 되므로 빠르게 변경할 수 있습니다.

3. 쉬운 반응형 디자인

간단한 접두사(sm:, md:, lg:, xl:)를 사용하여 반응형 디자인을 빠르게 구현할 수 있습니다.

<div class="text-sm md:text-base lg:text-lg">
  화면 크기에 따라 크기가 변하는 텍스트
</div>

4. 커스터마이징 가능

Tailwind CSS는 tailwind.config.js 파일을 통해 색상, 간격, 폰트 등을 프로젝트에 맞게 커스터마이징할 수 있습니다. 이를 통해 프로젝트의 아이덴티티에 맞는 디자인 시스템을 구축할 수 있습니다.

// tailwind.config.js 예시
export default {
  theme: {
    extend: {
      colors: {
        primary: '#3490dc',
        secondary: '#ffed4a',
        danger: '#e3342f',
      },
    }
  }
}

5. 최적화된 빌드 크기

Tailwind CSS는 사용한 클래스만 포함된 CSS 파일을 생성하여 최종 파일 크기를 최소화합니다. 이는 웹사이트의 로딩 속도 향상에 도움이 됩니다.

🔍 Tailwind CSS 4.0에서 발생한 PostCSS 플러그인 오류 해결 방법

Tailwind CSS의 이러한 장점들 때문에 프로젝트에 사용하려 했지만, 버전 4.0에서 발생한 PostCSS 플러그인 오류로 인해 어려움을 겪었습니다.

문제 상황: Tailwind CSS 4.0의 PostCSS 플러그인 오류

설정 과정에서 다음과 같은 오류 메시지가 발생했습니다:

[postcss] It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

처음에는 임시 해결책으로 아래의 코드를 HTML의 <body> 영역에 추가했지만, 이는 개발 환경용 임시방편이라는 생각이 들었습니다 ,,

<script src="https://cdn.tailwindcss.com"></script>

🧐 원인 분석: Tailwind CSS 4.0의 구조적 변화

이 오류가 발생한 핵심 원인은 Tailwind CSS 4.0 버전부터 PostCSS 플러그인이 별도의 패키지로 분리되었기 때문입니다. 이전 버전에서는 tailwindcss 패키지 자체가 PostCSS 플러그인 역할을 했지만, 4.0 버전부터는 구조가 변경되었습니다.

🛠️ 해결 단계: 단계별 접근법

1단계: @tailwindcss/postcss 패키지 설치

첫 번째로 새로운 PostCSS 플러그인 패키지를 설치해야 합니다.

npm install @tailwindcss/postcss --save-dev

2단계: PostCSS 설정 파일 수정

다음으로 postcss.config.js 파일을 ES 모듈 형식으로 수정해야 합니다.

// 변경 전 (오류 발생)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

// 변경 후 (정상 작동)
export default {
  plugins: {
    "@tailwindcss/postcss": {}, // tailwindcss 대신 @tailwindcss/postcss 사용
    autoprefixer: {},
  }
}

3단계: CSS 파일 수정 (index.css)

Tailwind CSS 4.0에서는 CSS 파일의 작성 방식도 달라졌습니다. 기존의 지시문 대신 간단한 import문을 사용합니다.

/* 변경 전 (Tailwind CSS 3.x) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 변경 후 (Tailwind CSS 4.0) */
@import "tailwindcss";

4단계: 개발 서버 재시작

설정 파일을 수정한 후 개발 서버를 다시 시작합니다 !!

npm run dev

지금까지 PostCSS 플러그인 방식으로 테일윈드 CSS 4.0을 설정하는 방법에 대해 설명했습니다.

그런데 테일윈드 CSS 공식 문서를 살펴보니, 테일윈드 CSS 4.0은 다양한 프로젝트 환경에 맞는 여러 설치 방법을 제공하고 있었습니다 😳

Using Vite: Vite 플러그인으로 테일윈드 CSS를 설치하는 방법으로, Laravel, SvelteKit, React Router, Nuxt, SolidJS와 같은 프레임워크와 가장 원활하게 통합할 수 있습니다.
Using PostCSS: PostCSS 플러그인으로 테일윈드 CSS를 설치하는 방법으로, Next.js와 Angular 같은 프레임워크와 가장 원활하게 통합되는 방식입니다.
Tailwind CLI: 테일윈드 CLI 도구를 사용하는 방법으로, 처음부터 테일윈드 CSS를 설정하는 가장 간단하고 빠른 방법입니다. Node.js 없이 사용하고 싶다면 독립 실행형 실행 파일로도 제공됩니다.
Framework Guides: 다양한 환경에서 테일윈드 CSS를 설치하는 권장 접근 방식을 다루는 프레임워크별 가이드입니다.
Play CDN: 빌드 단계 없이 브라우저에서 바로 테일윈드를 사용해볼 수 있는 방법입니다. Play CDN은 개발 목적으로만 설계되었으며, 프로덕션 환경에서는 사용하지 않는 것이 좋습니다.

제 프로젝트는 Vite + React 환경이었기 때문에, Vite 플러그인 방식이 더 적합했을 수 있습니다. 처음에는 PostCSS 방식으로 문제를 해결했지만, 이후 Vite 플러그인 방식을 적용했습니다 !

따라서 Vite를 사용하는 프로젝트라면 아래의 방법을 통해 테일윈드 CSS 4.0을 더 효율적으로 설정할 수 있습니다 !

Using Vite

Vite 기반 프로젝트에서는 PostCSS 설정을 직접 다루는 대신, 테일윈드 CSS용 Vite 플러그인을 활용하면 설정이 더 간단합니다. 다음과 같은 단계로 쉽게 설정할 수 있습니다 !

1. 먼저 Vite 플러그인을 설치합니다.

npm install -D @tailwindcss/vite

2. vite.config.js 파일을 다음과 같이 수정합니다.

@tailwindcss/vite 플러그인을 Vite 구성에 추가합니다.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
})

3. index.css 파일은 동일하게 수정합니다.

@import "tailwindcss";

4. 개발 서버를 재시작합니다 !

npm run dev

➕ 추가 팁: 프로젝트 구조 관련 문제 해결

위에서 설명한 PostCSS 플러그인 문제 외에도, 프로젝트 구조가 복잡한 경우 다음과 같은 추가 문제가 발생할 수 있습니다:

npm error Missing script: "dev"

💡 참고 : 이는 명령어를 잘못된 디렉터리에서 실행했을 때 흔히 발생하는 문제입니다.

다음 명령어로 package.json 파일의 위치를 찾아볼 수 있습니다:

find . -name "package.json" -not -path "*/node_modules/*"

올바른 디렉터리로 이동한 후 명령어를 실행하면 해결됩니다:

cd correct/directory/path
npm run dev

💡 VS Code에서의 Tailwind CSS 개발 팁

1. Tailwind CSS IntelliSense 확장 프로그램 설치

VS Code 마켓 플레이스에서 Tailwind CSS IntelliSense를 검색하고 설치하세요 !
클래스 자동 완성, 문법 강조, 호버 시 미리보기 등 다양한 기능을 제공합니다.

2. 자주 사용되는 클래스 외우기

자주 사용되는 클래스 이름(p-4, text-lg, flex, items-center 등)을 외우면 개발 속도가 훨씬 빨라집니다 !!
Tailwind CSS 공식 문서를 자주 참고하세요 📋

Tailwind CSS는 빠른 개발 속도와 일관된 디자인 시스템을 제공하는 CSS 프레임워크입니다.

4.0 버전에서의 PostCSS 플러그인 문제는 구조적 변화로 인한 것이지만, @tailwindcss/postcss 패키지 설치와 설정 파일 수정으로 쉽게 해결할 수 있습니다 ! 처음에는 저도 이 오류 메시지를 보고 당황했지만, 원인을 파악하고 나니 생각보다 간단하게 해결할 수 있었습니다.

이러한 초기 설정 문제만 해결하면, Tailwind CSS의 모든 장점을 활용하여 효율적인 UI 개발을 할 수 있습니다. 앞으로 프로젝트에 Tailwind CSS를 도입할 때는 이 글에서 공유한 해결 방법을 참고하여 쉽게 설정하실 수 있기를 바랍니다 !!

🔗 참고자료

https://tailwindcss.com/docs/installation/using-postcss

Installing with PostCSS - Installation

Integrate Tailwind CSS with frameworks like Next.js and Angular.

tailwindcss.com

https://tailwindcss.com/docs/installation/using-vite

Installing with Vite - Installation

Integrate Tailwind CSS with frameworks like Laravel, SvelteKit, React Router, and SolidJS.

tailwindcss.com

https://velog.io/@oneook/tailwindcss-4.0-%EB%AC%B4%EC%97%87%EC%9D%B4-%EB%8B%AC%EB%9D%BC%EC%A1%8C%EB%82%98%EC%9A%94

tailwindcss 4.0 무엇이 달라졌나요?

Tailwind CSS v4.0은 성능과 유연성을 극대화한 새로운 버전으로, 최신 웹 표준과 개발 흐름에 맞춘 다양한 기능과 개선 사항을 제공합니다. 이 글에서는 업데이트된 주요 내용을 살펴봅니다.

velog.io

'3주차' 카테고리의 다른 글

tailwind-css / emotion-css / vanilla-extract (0)	2025.05.03
styled-components와 @emotion/styled (0)	2025.05.02
상태 관리 (0)	2025.05.02
Emotion CSS-in-JS (0)	2025.05.02
React 의 클로저 (0)	2025.05.02

SWEB 팀 블로그

Tailwind CSS 4.0 설정 문제 해결하기: PostCSS 플러그인 오류부터 Vite 설정까지

🎨 Tailwind CSS

Tailwind CSS란 ?

Tailwind CSS의 장점

🔍 Tailwind CSS 4.0에서 발생한 PostCSS 플러그인 오류 해결 방법

문제 상황: Tailwind CSS 4.0의 PostCSS 플러그인 오류

🧐 원인 분석: Tailwind CSS 4.0의 구조적 변화

🛠️ 해결 단계: 단계별 접근법

1단계: @tailwindcss/postcss 패키지 설치

2단계: PostCSS 설정 파일 수정

3단계: CSS 파일 수정 (index.css)

4단계: 개발 서버 재시작

Using Vite

💡 VS Code에서의 Tailwind CSS 개발 팁

1. Tailwind CSS IntelliSense 확장 프로그램 설치

2. 자주 사용되는 클래스 외우기

🔗 참고자료

'3주차' 카테고리의 다른 글

티스토리툴바

Tailwind CSS 4.0 설정 문제 해결하기: PostCSS 플러그인 오류부터 Vite 설정까지

🎨 Tailwind CSS

Tailwind CSS란 ?

Tailwind CSS의 장점

🔍 Tailwind CSS 4.0에서 발생한 PostCSS 플러그인 오류 해결 방법

문제 상황: Tailwind CSS 4.0의 PostCSS 플러그인 오류

🧐 원인 분석: Tailwind CSS 4.0의 구조적 변화

🛠️ 해결 단계: 단계별 접근법

1단계: @tailwindcss/postcss 패키지 설치

2단계: PostCSS 설정 파일 수정

3단계: CSS 파일 수정 (index.css)

4단계: 개발 서버 재시작

Using Vite

💡 VS Code에서의 Tailwind CSS 개발 팁

1. Tailwind CSS IntelliSense 확장 프로그램 설치

2. 자주 사용되는 클래스 외우기

🔗 참고자료

'3주차' 카테고리의 다른 글

관련글

티스토리툴바