[Tailwind CSS] Tailwind CSS v4.1에서 PostCSS 사용하기

티스토리 뷰

Web/CSS

[Tailwind CSS] Tailwind CSS v4.1에서 PostCSS 사용하기

보간 2025. 9. 21. 00:42

서론

평소처럼 Tailwind CSS와 추가 플러그인을 설치해서 사용하다가, h-[<value>]등 일부 클래스가 적용되지 않는 문제가 발생했다..
문제 원인은 Tailwind CSS v4.1의 구성과 Tailwind CSS 3의 구성을 혼용했기 때문이었고, v4.1에 맞는 구성을 사용하여 해결했다. 생각해보니 올해 초에 비슷한 문제를 겪었었던 것 같은데, 또 실수를 반복한 것 같다. 따라서 이것을 계기로 postCSS란 무엇인가, 어떻게 작동하는가. Tailwind CSS v4.1에서는 PostCSS 를 어떻게 구성하는가에 대해 정리해보려고 한다..

PostCSS란 무엇인가

PostCSS는 JavaScript를 사용해 CSS를 변환하는 도구이다. "Post-(이후에)"라는 접두사가 말해주듯, CSS가 작성된 후에 그 코드를 가공(transform)하는 역할을 한다.
주요 기능

Autoprefixer: 최신 CSS 속성에 -webkit-, -moz- 같은 벤더 프리픽스(vendor prefixes)를 자동으로 붙여줘서 크로스 브라우징을 지원
Tailwind CSS (v3까지): Tailwind CSS 플러그인이 PostCSS를 통해 @tailwind 지시문(directive)을 실제 CSS 클래스로 변환
CSS Nano, CSS Optimizer: CSS 파일을 압축하고 최적화하여 파일 크기를 축소

PostCSS가 Tailwind CSS에서 작동하는 과정 - v3, v4 비교

Tailwind CSS v3 - PostCSS 작동 과정

1. PostCSS가 CSS 파일을 파싱

먼저, PostCSS는 개발자가 작성한 CSS 파일을 읽어 들여서 AST(Abstract Syntax Tree, 추상 구문 트리)라는 구조로 변환한다.
v3 CSS 예시:

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

@layer components {
  .btn { @apply px-3 py-2 rounded; }
}

PostCSS는 이 코드를 AtRule 노드들을 가진 AST로 파싱한다:

// @tailwind base의 AST 구조 예시
{
  "type": "AtRule",       // 👈 규칙을 나타내는 노드
  "name": "tailwind",     // 👈 "@" 뒤의 이름
  "params": "base"        // 👈 이름 뒤의 매개변수
}

type: 이 노드의 종류를 나타낸다. @로 시작하는 규칙(예: @media, @import)을 CSS에서는 At-rule이라고 부르며, PostCSS에서는 이를 AtRule 타입으로 표현한다.
name: @ 기호 바로 다음에 오는 이름. 이 경우 "tailwind".
params: 이름 뒤에 오는 매개변수. 여기서는 "base".

*PostCSS는 AST Explorer라는 전용 도구를 제공한다. 이 웹사이트에 CSS 코드를 입력하면, 해당 코드가 어떻게 AST로 파싱되는지 실시간으로 시각화해서 보여준다

2. Tailwind CSS 플러그인(v3)이 AST를 변환

PostCSS 설정 (v3):

module.exports = {
  plugins: {
    tailwindcss: {},      // 👈 이 플러그인이 핵심 역할
    autoprefixer: {},
  },
}

v3에서의 변환 과정:

플러그인 실행: tailwindcss 플러그인은 PostCSS 체인에서 실행되며, AST를 순회하면서 다음을 찾는다:
- @tailwind 지시문
- @apply 지시문
- @layer 지시문
- @variants 지시문
지시문별 처리:
- @tailwind base → Tailwind의 normalize.css, 기본 스타일로 교체
- @tailwind components → 컴포넌트 레이어의 사용자 정의 스타일들로 교체
- @tailwind utilities → flex, text-center, p-4 등 유틸리티 클래스들로 교체
- @apply px-3 py-2 → padding-left: 0.75rem; padding-right: 0.75rem; padding-top: 0.5rem; padding-bottom: 0.5rem;로 교체
AST 노드 교체: 각 지시문 노드를 실제 CSS 규칙들로 대체한다.
다른 플러그인과의 상호작용: autoprefixer 등 다른 PostCSS 플러그인들이 순서대로 실행된다.

Tailwind CSS v4에서의 작동 과정

1. Tailwind 내부 파이프라인이 우선 처리

v4 CSS 예시:

@import "tailwindcss";
/* 또는 세분화된 import */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

2. v4의 이중 처리 구조

PostCSS 설정 (v4):

export default {
  plugins: {
    "@tailwindcss/postcss": {},  
  },
}

v4에서의 변환 과정:
1. Tailwind 내부 엔진이 먼저 처리

자체 파서 실행: Tailwind v4는 PostCSS와 독립적인 자체 파서를 사용한다.
@import 모듈 해석: @import "tailwindcss"를 모듈 로딩처럼 해석한다:
`@import "tailwindcss/base"` → base 모듈 로드 `@import "tailwindcss/components"` → components 모듈 로드 `@import "tailwindcss/utilities"` → utilities 모듈 로드
자체 AST에서 변환 완료: Tailwind 내부에서 모든 핵심 변환을 완료한다.
소스 스캔 및 최적화: 프로젝트 파일을 스캔해서 사용되는 클래스만 포함시킨다.

2. PostCSS 플러그인이 후처리

@tailwindcss/postcss 플러그인: 이미 변환된 CSS를 PostCSS AST로 전달한다.
브릿지 역할: v4 엔진의 결과물을 PostCSS 생태계와 연결해준다.
후처리 플러그인: 필요시 다른 PostCSS 플러그인들이 최종 처리를 한다.

핵심 차이점

처리 주체의 변화

v3: PostCSS가 주도하고, tailwindcss 플러그인이 AST를 변환
v4: Tailwind 자체 엔진이 주도하고, PostCSS는 보조 역할

지시문 처리 방식

v3: @tailwind base → AST에서 해당 노드를 찾아 CSS 규칙으로 교체
v4: @import "tailwindcss/base" → 모듈 시스템처럼 해당 블록을 포함

플러그인 체인에서의 위치

v3: PostCSS 체인의 한 단계로서 다른 플러그인들과 순서 의존성 있음
v4: 대부분의 작업을 사전에 완료하고, PostCSS는 최종 단계에서만 관여

성능과 안정성

v3: 플러그인 간 순서 충돌, 복잡한 의존성 관리 필요
v4: 독립적 처리로 순서 충돌 최소화, 더 빠른 빌드

// v3에서 문제가 생기면
module.exports = {
  plugins: {
    'postcss-import': {},
    'postcss-nesting': {},  // ← 순서 바뀌면 @apply 오류
    'tailwindcss': {},      // ← 다른 플러그인과 상호작용
    'autoprefixer': {},
  },
}

// v4에서는 단순함
export default {
  plugins: {
    "@tailwindcss/postcss": {},  // 대부분 처리 완료된 상태
  },
}

이렇게 v4에서는 처리 주체가 PostCSS에서 Tailwind 자체 엔진으로 이동하면서, PostCSS는 최종 단계의 보조적 역할만 담당하게 되었다. 이로 인해 빌드가 더 안정적이고 빨라졌다.
+ Tailwind CSS 4.0 알파에서는 mjs나 js 설정파일 없이도 플러그인 사용이 가능했으나, 4.1에서는 postcss.config.mjs 구성을 권장하고 있다.

Tailwind CSS에서 Post CSS 구성하기- v3, v4.1 비교

1. Tailwind CSS 설치

tailwindcss, @tailwindcss/postcss, postcss 설치

npm install tailwindcss @tailwindcss/postcss postcss

**
v3에서, tailwindcss 패키지가 PostCSS 플러그인이었지만, **v4에서는 PostCSS 플러그인이 전용 @tailwindcss/postcss' 패키지에 저장된다. v3에서는 PostCss 설정파일에서는 require('tailwindcss')처럼 해당 패키지를 직접 불러와서 사용했다. 즉, 역할이 분리되었다.

tailwindcss 패키지: 이제는 Tailwind의 핵심 엔진만 포함된다.
@tailwindcss/postcss 패키지: 이 패키지는 PostCSS 플러그인 역할만 담당한다. 즉, PostCSS와의 호환성을 위해 따로 분리된 경량화된 플러그인.

2. Tailwind에 PostCSS 구성을 추가

//postcss.config.mjs

export default {
  plugins: {
    /*"postcss-import": {}, //v3 */
    /* tailwindcss: {}, //v3 */
    /*autoprefixer: {}, //v3 */
    "@tailwindcss/postcss": {},
  },
};

postcss.config.mjs 파일 또는 내 프로젝트의 PostCSS 구성에 @tailwindcss/postcss를 추가한다. v4에서는 imports와 vendor prefixing이 자동적으로 처리되기 때문에, 'postcss-import'와 'autoprefixer'을 프로젝트에서 제거할 수 있다.

3. Import Tailwind CSS

CSS

@import "tailwindcss";

Tailwind CSS를 import할 CSS 파일에 @import "tailwindcss"를 추가한다.
v3에서는 @tailwind base;와 같은 지시문을 사용했으나, v4에서는 이 한 줄의 사용이면 충분하다.

이 외 자세한 사용방법은 https://tailwindcss.com/docs/installation/using-postcss를 참고해보자.

마무리

tailwind를 자주 사용하면서도 PostCSS는 다소 기계적으로 구성했는데, 이번에 어떤 것인지 잘 알아보았다. 다음 구성 때는 무엇이 문제인지 더 빠르게 파악할 수 있을 것 같다.

공지사항

최근에 올라온 글

최근에 달린 댓글

Total

Today

Yesterday

링크

TAG more

« 2025/11 »
일	월	화	수	목	금	토
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30

글 보관함

회고

티스토리 뷰