Laravel Vite
이 문서는 Laravel에서 Vite가 언제부터 도입되었는지, 기존 Laravel Mix에서 Vite로 전환하는 가장 쉬운 방법, 그리고 Vite의 기본적인 사용법을 정리한 가이드입니다.
1. Vite 도입 시기
Laravel 9 (2022년 2월 출시)부터 Vite가 기본 에셋 번들러(Asset Bundler)로 공식 채택되었습니다.
이전 버전까지는 Webpack을 기반으로 한 Laravel Mix가 기본값이었으나, 훨씬 빠른 개발 서버 구동 속도와 빌드 성능을 제공하는 Vite로 대체되었습니다.
2. Laravel Mix에서 Vite로 마이그레이션
기존 Laravel Mix 프로젝트를 Vite로 전환하는 가장 쉬운 방법은 다음 단계를 순서대로 따르는 것입니다.
1단계: package.json 의존성 변경
먼저 기존 Mix 관련 패키지를 삭제하고 Vite 관련 패키지를 설치합니다.
// package.json
// 1. 아래 의존성을 삭제하세요.
"devDependencies": {
"laravel-mix": "^6.0.6",
"webpack": "...",
"resolve-url-loader": "...",
// 기타 mix 관련 플러그인들...
}
// 2. 아래 의존성을 추가하세요.
"devDependencies": {
"axios": "^1.1.2",
"laravel-vite-plugin": "^1.0.0",
"vite": "^5.0.0"
}
터미널에서 아래 명령어로 의존성을 업데이트합니다.
# 기존 node_modules 폴더와 package-lock.json 파일을 삭제하여 충돌 방지
rm -rf node_modules
rm package-lock.json
# 새로운 의존성 설치
npm install
2단계: webpack.mix.js 파일을 vite.config.js로 교체
프로젝트 루트에 있는 webpack.mix.js 파일을 삭제하고, 그 자리에 vite.config.js 파일을 새로 만듭니다.
// vite.config.js (새 파일)
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
// 진입점(Entry Points)이 될 JS와 CSS 파일을 지정합니다.
input: ['resources/css/app.css', 'resources/js/app.js'],
// 페이지가 새로고침될 때 전체 리로드를 트리거할 파일을 지정합니다.
refresh: true,
}),
],
});
팁:
input배열에는 프로젝트에서 사용하는 모든 CSS와 JS 진입점 파일을 넣어주어야 합니다. 예를 들어, 어드민 페이지용 CSS가 따로 있다면['resources/css/app.css', 'resources/css/admin.css', 'resources/js/app.js']와 같이 추가합니다.
3단계: package.json 스크립트 수정
package.json 파일의 scripts 부분을 Mix 명령어에서 Vite 명령어로 변경합니다.
변경 전 (Mix)
"scripts": {
"dev": "npm run development",
"development": "mix",
"watch": "mix watch",
"prod": "npm run production",
"production": "mix --production"
}
변경 후 (Vite)
"scripts": {
"dev": "vite",
"build": "vite build"
}
4단계: Blade 파일의 @mix 헬퍼를 @vite 디렉티브로 교체
resources/views/**/*.blade.php 파일들에서 에셋을 불러오는 방식을 변경해야 합니다.
변경 전 (Mix)
<head>
...
<link rel="stylesheet" href="{{ mix('css/app.css') }}">
<script src="{{ mix('js/app.js') }}" defer></script>
</head>
변경 후 (Vite)
<head>
...
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
@vite 디렉티브는 인자로 vite.config.js의 input에 명시한 진입점 파일들을 배열 형태로 받습니다.
5단계: 환경 변수 접두사 변경
만약 .env 파일에서 MIX_ 접두사를 사용해 JavaScript로 변수를 넘겼다면, 이제 VITE_ 접두사로 변경해야 합니다.
변경 전 (.env)
MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
변경 후 (.env)
VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
JavaScript 코드에서도 process.env.MIX_ 를 import.meta.env.VITE_ 로 변경해야 합니다.
3. Vite 기본 사용법
개발 서버 실행
터미널에서 아래 명령어를 실행하면 Vite 개발 서버가 시작됩니다.
npm run dev
이 서버는 엄청나게 빠른 속도로 변경 사항을 감지하고 브라우저에 즉시 반영합니다(Hot Module Replacement, HMR). 더 이상 npm run watch처럼 파일을 저장할 때마다 몇 초씩 기다릴 필요가 없습니다.
프로덕션 빌드
배포를 위해 에셋 파일들을 컴파일하고, 압축하고, 버전 해시를 붙이려면 아래 명령어를 사용합니다.
npm run build
이 명령어를 실행하면 public/build 디렉터리에 최적화된 최종 에셋 파일들과 manifest.json 파일이 생성됩니다.
Blade 파일에서 에셋 포함하기
@vite() 디렉티브는 개발 환경과 프로덕션 환경을 자동으로 감지하여 다르게 동작합니다.
npm run dev실행 중 (개발 환경): Vite 개발 서버(http://localhost:5173)를 가리키는 스크립트를 삽입하여 HMR이 작동하도록 합니다.npm run build실행 후 (프로덕션 환경):public/build폴더에 생성된, 버전 해시가 붙은 최종 CSS와 JS 파일을 가리키는<link>와<script>태그를 생성합니다.
개발자는 환경에 대해 신경 쓸 필요 없이 @vite() 디렉티브 하나만 사용하면 됩니다.
4. 주요 명령어 요약
npm install: Vite와laravel-vite-plugin등 필요한 패키지를 설치합니다.npm run dev: 개발 서버를 실행합니다. 개발 중에는 이 명령어를 계속 켜두면 됩니다.npm run build: 프로덕션 배포를 위해 모든 에셋을 빌드하고 최적화합니다.