라라벨 프로젝트에서 tailwindcss 버전 4로 업그레이드 및 에러 해결법

이번 포스트는 라라벨 프로젝트에 설치된 tailwindcss의 버전을 업그레이드해 보겠다.

갑자기 웬 tailwindcss의 버전 업그레이드인가 싶겠지만, 다음 포스트를 위해서는 이 작업이 필요하다.

미리 살짝 언급하자면, 곧 filament를 설치하려고 하는데 5 버전을 설치하기 위함이다.

이전 포스트

라라벨 블레이드 컴포넌트 활용: 다크 모드 버튼을 컴포넌트로 추출하기

라라벨 블레이드 컴포넌트 추출을 통해 다크 모드 버튼을 모듈화하는 방법입니다. Alpine.js의 x-data 빈 속성 활용법과 전역 스토어 연동 원리를 설명하고, 모바일 화면에도 다크 모드 버튼이 표시되도록 뷰 파일을 수정하는 팁도 공유합니다.

현재 tailwindcss의 버전이 '3'이다

package.json 파일을 확인해 보니, 현재 라라벨 프로젝트의 tailwindcss 버전이 3이다.

4가 나온지 1년 이상 지난 것으로 아는데, 최근에 설치한 라라벨 프로젝트에서는 여전히 3을 쓰고 있다니..

직접 업그레이드해 보도록 하겠다.

Upgrade guide - Getting started - Tailwind CSS

Upgrading your Tailwind CSS projects from v3 to v4.

tailwindcss.com

그전에 먼저 이 문서를 살펴보자.

tailwindcss의 업그레이드에 대해서 안내하고 있는데, 여기 나온 것처럼 3과 4의 클래스 이름이 약간 달라졌다.

그래서 '업그레이드를 하면 기존의 뷰 파일에 있는 tailwindcss의 클래스들을 다 수정해야 하나?'라고 생각할 수도 있는데, 업그레이드 명령어를 입력하면 tailwindcss의 버전을 3에서 4로 업그레이드해주는 것뿐만 아니라, 기존의 뷰 파일의 클래스들도 다 바꿔준다.

tailwindcss 업그레이드

make app #컨테이너 안으로 들어간다.
npx @tailwindcss/upgrade

VSCode의 터미널에서 이 명령어들을 차례대로 실행한다.

Need to install the following packages:
@tailwindcss/upgrade@4.3.2
Ok to proceed? (y)

그러면 이렇게 뜨는데, 'y'를 입력하고 enter 키를 누르자.

업그레이드가 완료된 후에 다시 package.json 파일을 확인하면 이렇게 tailwindcss의 버전이 4로 올라간 것을 확인할 수 있다.

그런데 이게 끝이 아니다.

현재 상태로 첫 화면으로 가면 이렇게 에러가 뜬다.

vite.config.js 파일 수정

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from "@tailwindcss/vite"; // 추가

export default defineConfig({
    plugins: [
        tailwindcss(), // 추가
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    // 생략
});

주석으로 // 추가라고 표시해 놓은 두 줄이 추가됐다.

임포트^Import는 순서가 상관없지만, plugins: [ ... ]의 내부에서는 tailwindcss를 라라벨 플러그인보다 위에 배치해야 안정적으로 빌드되니 주의하도록 하자.

rm -rf node_modules package-lock.json

ubuntu에서 이 명령어를 실행해서 기존 node_modules 폴더를 삭제한다.

버전 꼬임으로 인해 노드 모듈에 캐싱된 에러 파편을 청소하기 위해서다.

npm install
npm run dev

그다음에는 make app 명령어로 컨테이너 안으로 들어갔던 VSCode의 터미널에서 이 명령어들을 차례대로 실행한다.

그리고 다시 라라벨 웹 애플리케이션의 첫 화면을 확인하면, 이제는 에러가 발생하지 않는다.

그동안 tailwindcss 3의 클래스들에 익숙해져 있었는데, 4에 빠르게 잘 적응할 수 있을지 모르겠다.

하지만 filament 5를 설치하기 위해서는 어쩔 수 없이 거쳐야 하는 과정이다.