Vite + React에서 Tailwind 설치 중 버전 오류

환경

• OS: Windows
• 스택: Vite + React (+ TypeScript), ESLint/Prettier
• Node: 22.16.0
• 상황: Vite + React에서 Tailwind 설치 진행

증상

npm i -D tailwindcss postcss autoprefixer npx tailwindcss init -p

에러:

• npm error could not determine executable to run
• 'tailwindcss'은(는) 내부 또는 외부 명령이 아닙니다.

원인(핵심)

• Tailwind v4 변화: v4부터 npx tailwindcss init -p 흐름이 사실상 빠졌고, 프레임워크별 가이드(Vite)는 init 없이 수동 설정으로 전환됨.
• Windows에서 npx 해석 꼬임: bin 해석/캐시가 꼬이면 “실행 대상을 못 찾는다” 에러가 뜸. v4에서 특히 자주 관측.

즉, v4 + npx 조합에서 실행 대상 파악 실패로 터진 것.

 

해결: Tailwind를 v3로 고정 설치

npm install tailwindcss@3

npm i -D tailwindcss@3 postcss autoprefixer
.\node_modules\.bin\tailwindcss init -p

• tailwind.config.js, postcss.config.js 생성 성공
• tailwind.config.js의 content 경로 정정
• index.css에 @tailwind base; @tailwind components; @tailwind utilities; 추가
• 앱에서 import "./index.css" 확인
• 테스트 컴포넌트 유틸 클래스 정상 적용 확인

 

v4로 그대로 쓰고 싶은 경우(대안)

v4는 init 명령 없이 수동 설정 권장.

1. 설치

npm i -D tailwindcss postcss autoprefixer

2. 직접 파일 생성

# postcss.config.js
export default {
  plugins: { tailwindcss: {}, autoprefixer: {} },
};

# src/index.css 맨 위에
@tailwind base;
@tailwind components;
@tailwind utilities;

 

 

3. 엔트리에서 import "./index.css"

4. 필요 시 theme.extend.colors에 bg-background 같은 커스텀 토큰 매핑

재발 방지 체크리스트

• 프로젝트 루트에서 실행했는지 확인(package.json 보이는 위치)
• .\node_modules\.bin\tailwindcss 경로 실행 기억
• tailwind.config.js의 content 경로: ./index.html, ./src/**/*.{js,jsx,ts,tsx}
• index.css에 @tailwind 3줄 + 엔트리에서 임포트
• Figma 커스텀 토큰(bg-background)은 extend.colors에 매핑

TL;DR

• v3 쓰거나 v4는 수동 설정하면 해결됨.

---

참고 출처

• https://j-lisa-dev.tistory.com/90
• https://stackoverflow.com/questions/79386415/error-could-not-determine-executable-to-run-when-initializing-tailwind-css-with-shadcn-ui