[ACE_Monster] React+tailwindCSS

본문 읽기 전에 공식문서 참고하고 해결해보시길!

그래도 안된다면 아래 찬찬히~ 읽어보세요

급한분들은 바로가잣!

• Tailwind CSS v4 공식 업그레이드 가이드 : https://tailwindcss.com/docs/upgrade-guide
• Vite 공식 문서: https://vitejs.dev/config/
• Tailwind CSS v4.0 블로그 포스트: https://tailwindcss.com/blog/tailwindcss-v4
• PostCSS 설정 가이드: https://tailwindcss.com/docs/installation#postcss-setup

Installing with Vite - Installation

 

Tailwind CSS v4.0

 

Vite

 

Upgrade guide - Getting started

 

 

 

 

---

 

React + Vite + pnpm 프로젝트에 Tailwind CSS를 도입하며 만날 수 있는 네 가지 문제를 모두 해결하는 방법을 담았습니다.
1. tailwindcss init 명령이 먹통인 이유
2. ES 모듈(CommonJS) 충돌
3. pnpm 바이너리 링크 이슈
4. Husky + lint-staged + Prettier 커밋 훅 충돌

 

pnpm create vite@latest

 

패키지 매니저 pnpm쓰기로 했는데 까먹고 npm으로 비트 생성해버렸다 상관없음

프로젝트 루트에서 node_modules 폴더와 package-lock.json 삭제하고 의존성 설치해주면 된다.

rm -rf node_modules package-lock.json
pnpm install

 

난 커밋하는 순간 자동으로 검사하는 기능을 추가했기때문에 본문 중에 언급이 있을 수 있다.

하 근데 문제는 어느순간부터 비트에 테일윈드를 설치하려고하면 테일윈드 초기화가 안된다는 점이다. 우씨💢

 

공식문서를 읽어보니 버전문제였다

[주의사항]
Node.js는 16.x 이상, pnpm은 7.x 이상(v10.x 권장), Vite는 4.x 이상, React는 18.x 이상을 사용하세요.
(선택) 만약 package.json에 "type": "module"을 넣어두셨다면, ES 모듈로 동작하기 때문에 설정 파일 확장자에 주의해야 합니다.

 

 

 

지금부터 비트에 테일윈드 설치가 안된 이유와 설치하는 법을 기재하겠다.

---

Tailwind CLI ‘init’ 명령이 동작하지 않는 이유

• Tailwind CSS 4버전부터는 init 커맨드를 CLI에서 제거했습니다.
• 예전(v3)에는 다음과 같이 실행 파일이 생기고 설정 파일을 자동 생성했지만,

 

pnpm add -D tailwindcss@3 postcss autoprefixer
pnpm exec tailwindcss init -p
# → node_modules/.bin/tailwindcss 가 실행되어
# tailwind.config.js, postcss.config.js 자동 생성

1. • v4 이상을 설치하면 실행 파일 자체가 없어서,

 pnpm add -D tailwindcss@4 postcss autoprefixer
pnpm exec tailwindcss init -p
# → ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL: Command "tailwindcss" not found

• 이 때문에 자동 생성 명령이 먹통이 됩니다.

2. ES 모듈(CommonJS) 충돌 문제

• package.json에 "type": "module"을 설정하면 .js 파일이 모두 ESM(ES Module)으로 처리됩니다.
• 그러나 Tailwind 설정 파일(postcss.config.js, tailwind.config.js)은 전통적인 CommonJS 문법(module.exports = …)을 쓰기 때문에,

ReferenceError: module is not defined in ES module scope
This file is being treated as an ES module…

1. • 이 오류를 피하려면 설정 파일을 .cjs 확장자로 바꿔 CommonJS로 강제하거나, "type": "module"을 제거해야 합니다.

3. pnpm 바이너리 링크 이슈

• pnpm은 node_modules/.bin에 실행 파일을 반드시 생성하지 않을 수 있습니다.
• CLI가 동작하지 않을 때는 수동 설정 파일 작성이나 버전 조정을 통해 우회합니다.

4. Git 훅(Husky + lint-staged + Prettier) 충돌

• 설정 파일을 .cjs로 바꾸면, 커밋 전에 Prettier 검사에서 걸릴 수 있습니다.
• .lintstagedrc.json 등에서 검사 대상 패턴에 cjs를 추가하세요.

 

{
  "**/*.{js,ts,jsx,tsx,cjs}": [
    "eslint --max-warnings=0",
    "prettier --check"
  ]
}

---

 

 

 

두 가지 해결 방법

 1. Tailwind v3으로 CLI 살리기

1. 기존 Tailwind를 제거하고 v3으로 설치

pnpm remove tailwindcss
pnpm add -D tailwindcss@3 postcss autoprefixer

 

2. 다시 init 명령 실행

pnpm exec tailwindcss init -p

3. tailwind.config.js와 postcss.config.js가 자동 생성됩니다.

 

 

 

 

2. Tailwind v4+에서 수동으로 설정 파일 만들기

1. 의존성 설치

pnpm add -D tailwindcss postcss autoprefixer

2. tailwind.config.cjs 파일 생성 (프로젝트 루트에)

 

module.exports = {
  content: [
    './index.html',
    './src/**/*.{js,jsx,ts,tsx}'
  ],
  theme: { extend: {} },
  plugins: [],
};

 

3. postcss.config.cjs 파일 생성

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

 

4. 입력용 CSS 파일 준비 (src/index.css)

 

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

 

5. React 진입점에 임포트 추가 (src/main.jsx 또는 src/index.jsx 최상단 모르겠으면 일단 해보기)

 

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './index.css';   // Tailwind CSS 적용

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode><App /></React.StrictMode>
);

 

6. 개발 서버 실행

pnpm run dev

소스코드 안에서

<div className="bg-red-500 text-white">제발제발제발제발 테일윈드</div>

 

와 같이 쓰면 Vite가 필요한 스타일만 골라 번들에 포함합니다.

 

---