Vite + Tailwind 4.x 설정 중 겪은 CJS/ESM 충돌과 PostCSS 오류 해결 기록

Vite + React + Tailwind 조합으로 프로젝트를 설정하는 과정에서 여러 오류가 발생했다. 대부분 CJS/ESM 문법 차이와 Tailwind 4.x의 구조 변경 때문에 생긴 문제였다. 아래는 실제 해결 과정을 기록한 내용이다.

1. 개발 환경

• Vite (React + TypeScript)
• Tailwind CSS 4.x
• pnpm
• macOS

2. 문제 1: Tailwind CLI가 실행되지 않음

설정 파일을 자동 생성하려고 아래 명령을 실행했다.

pnpm exec tailwindcss init -p

하지만 다음 오류가 발생했다.

Command "tailwindcss" not found

설치 자체는 되었지만 CLI 바이너리가 잡히지 않는 상태였다. 그래서 config 파일을 직접 작성하는 방식으로 변경했다.

3. 문제 2: .cjs 파일에서 ESM 문법 사용 → SyntaxError 발생

postcss.config.cjs 파일을 직접 만들며 아래처럼 작성했다.

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

실행 후 다음 오류가 발생했다.

SyntaxError: Unexpected token 'export'

원인

.cjs 확장자는 Node.js에서 CommonJS(CJS) 방식으로만 해석된다. 따라서 export default 같은 ESM 문법은 사용할 수 없다.

CommonJS vs ESM 비교

구분	CommonJS	ES Module
import	require()	import
export	module.exports	export
확장자	.js, .cjs	.js, .mjs

설정 파일은 번들러가 아니라 Node가 직접 읽는 파일이라 이 차이가 그대로 드러난다.

해결

아래처럼 CJS 문법으로 수정했다.

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

4. 문제 3: Tailwind 4.x에서 PostCSS 플러그인이 분리됨

CJS 문법 문제를 해결한 후, 이번에는 다음 오류가 발생했다.

It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
The PostCSS plugin has moved to a separate package.

원인

Tailwind 4.x부터 PostCSS 플러그인이 완전히 분리된 패키지(@tailwindcss/postcss)로 이동했다.

해결

먼저 플러그인을 설치한다.

pnpm add -D @tailwindcss/postcss

그리고 PostCSS 설정을 다음과 같이 변경한다.

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Tailwind 설정 파일(tailwind.config.cjs)은 기존 형태 그대로 사용해도 된다.

5. 전체 해결 요약

1. Tailwind CLI가 동작하지 않아 config 파일을 수동 생성
2. .cjs 파일에 ESM 문법 사용 → SyntaxError
3. Tailwind 4.x에서 PostCSS 플러그인이 분리되며 추가 오류 발생
4. CJS 문법으로 수정 + @tailwindcss/postcss 설치로 해결

6. 마무리

설정 파일은 Node가 직접 읽기 때문에 CJS/ESM 문법 차이에 민감하다.
또 Tailwind 4.x는 기존 방식과 변경된 부분이 많아 초기 설정에서 오류가 발생하기 쉽다. 주의하기!