Next.js 프로젝트에 Tailwind CSS 적용 중 발생한 문제와 해결 과정

1. 문제 상황

Next.js 프로젝트에 Tailwind CSS를 적용하려고 설치 후 npx tailwindcss init -p 명령어를 실행했으나, 다음과 같은 에러가 발생했다.

Error: could not determine executable to run

해당 에러는 tailwindcss CLI 실행 파일이 제대로 설치되지 않았을 때 발생하는 문제이다.

2. 시도했던 해결 방법

1. 기존에 설치된 tailwindcss-cli와 관련 의존성을 제거
2. 캐시 초기화 및 클린 설치 시도

rm -rf node_modules package-lock.json
npm uninstall tailwindcss postcss autoprefixer
npm cache clean --force

이후 다시 공식 패키지를 재설치하였다.

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

3. 정상 설치 후 발생한 PostCSS 관련 오류

Tailwind v3.4 이상부터는 tailwindcss를 PostCSS plugin으로 직접 사용할 수 없도록 변경되었다. 그래서 다음과 같은 에러가 발생했다:

Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
To continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss`...

해결 방법

1. @tailwindcss/postcss 설치

npm install -D @tailwindcss/postcss

2. postcss.config.js 수정

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
}

4. tailwind.config.js 정리

// tailwind.config.js
module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

5. 최종 확인

이제 Tailwind가 적용된 클래스들을 Next.js 프로젝트에서 사용할 수 있게 되었으며, globals.css에 아래 3줄이 포함되어 있어야 한다.

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

그리고 _app.js에서 글로벌 CSS를 불러와야 Tailwind가 전역에 적용된다.

// pages/_app.js
import '../styles/globals.css';

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

6. 결론

Tailwind CSS의 버전이 올라가면서 기존의 설정 방식이 바뀌었고, 이에 따라 새로운 플러그인인 @tailwindcss/postcss를 사용해야 하는 구조로 변경되었다.

처음엔 익숙하지 않아 혼란이 있었지만, 패키지와 설정 파일의 구조를 이해하고 최신 가이드대로 적용하면서 문제를 성공적으로 해결할 수 있었다.