[ Troubleshooting🛠️ ] Next.js에서 Tailwind CSS 설치 시 발생하는 오류 해결하기

 Next.js 프로젝트에 Tailwind CSS를 설치하는 과정에서 "npx tailwindcss init -p" 명령어를 실행했을 때 "could not determine executable to run" 오류가 발생하는 경우가 있었습니다. 이 글에서 이 문제의 원인과 해결 방법에 대해 정리해보겠습니다!

 

 

 

 

1.  문제 발생❓

Next.js 프로젝트를 설정하고 Tailwind CSS를 설치한 후 초기화 명령어를 실행했을 때 다음과 같은 오류가 발생했습니다.

npx tailwindcss init -p
npm error could not determine executable to run
npm error A complete log of this run can be found in: /Users/username/.npm/_logs/yyyy-mm-ddTHH_MM_SS_XXXZ-debug-0.log

 

 

 

2.  원인 추론 🔎

• Tailwind 설치까지는 잘되었습니다.

npm install -D tailwindcss postcss autoprefixer

 

• 하지만 초기 Tailwind 설정 파일을 생성하려고할 때 오류가 발생했습니다.

npx tailwindcss init -p

 

• 오류에서 나온 로그를 자세히 보기 위해 터미널에 "/Users/username/.npm/_logs/yyyy-mm-ddTHH_MM_SS_XXXZ-debug-0.log" 를 검색해보았습니다.

cat /Users/username/.npm/_logs/yyyy-mm-ddTHH_MM_SS_XXXZ-debug-0.log

 

• 로그를 살펴본 결과, 로그에서 verbose pkgid tailwindcss@4.1.0와 같은 정보를 확인할 수 있는데, 이는 Tailwind CSS 버전 4.x가 설치되어 있음을 의미합니다. 그래서 버전4 Tailwind와 관련된 오류를 구글에 검색해보았습니다. 저랑 같은 오류를 맞딱뜨린 사람이 많았습니다. 거기에서 원인을 파악했습니다.
• 바로, Tailwind CSS 버전 호환성 문제였습니다. 최근에 나온 Tailwind(버전 4.x)에서 CLI 구조가 변경되어 발생한 문제였습니다. 그래서 예전 버전에서 사용되었던 이 "npx tailwindcss init -p" 명령어가 오류가 났던 것입니다.

 

 

 

 

 

 

3.  해결 과정 📋

1. Tailwind CSS 3.x 버전으로 다운그레이드

npm install -D tailwindcss@3.4.17 postcss autoprefixer

 

• D 옵션은 -save-dev의 축약형으로, 패키지를 개발 의존성(devDependencies)으로 설치합니다. Tailwind CSS는 빌드 과정에서만 사용되므로 개발 의존성으로 설치하는 것이 적합합니다.

 

2. 버전을 다운그레이드 해주면 정상 작동합니다.

npx tailwindcss init -p

 

 

 

 

4.  결론 ❤‍🔥

 

간단히 설명하자면:

1. 처음에 npm install -D tailwindcss postcss autoprefixer 명령어로 설치했을 때, 자동으로 최신 버전인 Tailwind CSS 4.x가 설치되었습니다.
2. 그런데 이 4버전은 아직 새로운 버전이라 일부 명령어(특히 npx tailwindcss init -p)와 호환성 문제가 있었습니다.
3. 그래서 npm install -D tailwindcss@3.4.17 postcss autoprefixer 명령어로 더 안정적인 3버전으로 다운그레이드하니까 문제가 해결된 것입니다.

쉽게 말해, 너무 최신 버전을 설치해서 문제가 생겼고, 좀 더 안정적인 이전 버전으로 바꾸니 해결된 것입니다. 이 트러블슈팅이 Next.js와 Tailwind CSS를 설정하는 과정에서 도움이 되길 바랍니다. 추가적인 문제가 발생하면 로그 파일을 확인하여 더 자세한 정보를 얻을 수 있습니다!