프론트엔드(Vite)

번역일: 2026년 6월 25일

프론트엔드(Vite)

소개
설치 및 설정
Vite 실행하기
JavaScript 작업
- 별칭(Alias)
- Vue
- React
- Inertia
- URL 처리
스타일시트 작업
Blade 및 라우트 작업
에셋 프리페치
커스텀 기본 URL
환경 변수
테스트에서 Vite 비활성화
서버 사이드 렌더링(SSR)
스크립트 및 스타일 태그 속성
고급 커스터마이징
- 개발 서버 CORS 설정
- 개발 서버 URL 수정

소개

Vite는 현대적인 프론트엔드 빌드 도구로, 개발 환경에서 매우 빠른 속도를 제공하고 프로덕션 배포를 위한 코드 번들링을 지원합니다. Laravel로 애플리케이션을 개발할 때는 보통 Vite를 사용해 CSS와 JavaScript 파일을 프로덕션 에셋으로 변환합니다.

Laravel은 공식 플러그인과 Blade 디렉티브를 통해 Vite와 긴밀하게 통합되어 있어, 개발 환경과 프로덕션 환경 모두에서 에셋을 손쉽게 로드할 수 있습니다.

NOTE

기존에 Laravel Mix를 사용 중이신가요? 새로운 Laravel 프로젝트에서는 Vite가 Laravel Mix를 대체했습니다. Mix 문서는 Laravel Mix 웹사이트를 참고하세요. Vite로 전환하려면 마이그레이션 가이드를 참고하세요.

Vite와 Laravel Mix 중 선택하기

Vite 도입 이전에 Laravel은 webpack 기반의 Mix를 에셋 번들링에 사용했습니다. Vite는 JavaScript 중심의 풍부한 인터랙션을 가진 앱을 빠르고 생산적으로 개발하는 데 초점을 맞춥니다. Inertia 등을 활용한 SPA(싱글 페이지 애플리케이션) 개발이라면 Vite가 최적입니다.

Livewire처럼 JavaScript를 부분적으로 활용하는 서버 사이드 렌더링 방식의 전통적인 애플리케이션에도 Vite는 잘 맞습니다. 다만 JavaScript에서 직접 참조하지 않는 임의의 파일을 빌드 결과물에 포함하는 기능처럼, Laravel Mix만이 지원하는 일부 기능은 Vite에 없다는 점을 참고하세요.

Mix로 다시 돌아가기

Vite 스캐폴딩으로 시작한 프로젝트를 다시 Laravel Mix와 webpack으로 되돌려야 한다면 공식 Vite → Mix 마이그레이션 가이드를 참고하세요.

설치 및 설정

NOTE

아래 내용은 Laravel Vite 플러그인을 수동으로 설치하고 설정하는 방법을 설명합니다. Laravel의 스타터 킷은 이 모든 설정을 이미 포함하고 있으므로, 빠르게 시작하고 싶다면 스타터 킷을 활용하는 것이 가장 편리합니다.

Node 설치

Vite와 Laravel 플러그인을 실행하기 전에 Node.js(16 이상)와 NPM이 설치되어 있어야 합니다:

node -vnpm -v

Node.js 공식 웹사이트에서 최신 버전의 Node와 NPM을 설치할 수 있습니다. Laravel Sail을 사용 중이라면 Sail을 통해 Node와 NPM 명령을 실행할 수 있습니다:

./vendor/bin/sail node -v./vendor/bin/sail npm -v

Vite 및 Laravel 플러그인 설치

새로 생성한 Laravel 프로젝트의 루트 디렉터리에는 package.json 파일이 있습니다. 기본 package.json에는 Vite와 Laravel 플러그인을 사용하는 데 필요한 패키지가 이미 포함되어 있습니다. NPM으로 프론트엔드 의존성을 설치하세요:

npm install

Vite 설정

Vite는 프로젝트 루트의 vite.config.js 파일을 통해 설정합니다. 필요에 따라 자유롭게 커스터마이징할 수 있으며, @vitejs/plugin-vue나 @vitejs/plugin-react 같은 추가 플러그인도 설치해서 사용할 수 있습니다.

Laravel Vite 플러그인은 애플리케이션의 엔트리 포인트를 지정해야 합니다. JavaScript, CSS 파일은 물론 TypeScript, JSX, TSX, Sass 같은 전처리 언어 파일도 엔트리 포인트로 사용할 수 있습니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Inertia 등을 사용하는 SPA를 개발할 때는 CSS 엔트리 포인트 없이 구성하는 것이 좋습니다:

import { defineConfig } from 'vite';

import laravel from 'laravel-vite-plugin';

export default defineConfig({

    plugins: [

        laravel([

            'resources/css/app.css', //

            'resources/js/app.js',

]),

],

});

대신 CSS는 JavaScript 파일에서 직접 import 하세요. 보통 resources/js/app.js에 아래와 같이 추가합니다:

import './bootstrap';

import '../css/app.css'; //

Laravel 플러그인은 여러 엔트리 포인트와 SSR 엔트리 포인트 같은 고급 설정 옵션도 지원합니다.

HTTPS 개발 서버 사용하기

로컬 개발 웹 서버가 HTTPS로 애플리케이션을 제공하는 경우, Vite 개발 서버 연결에 문제가 생길 수 있습니다.

Laravel Herd에서 사이트를 보안 처리했거나, Laravel Valet에서 secure 명령어를 실행한 경우에는 Laravel Vite 플러그인이 자동으로 생성된 TLS 인증서를 감지하여 사용합니다.

애플리케이션 디렉터리명과 다른 호스트명으로 사이트를 보안 처리한 경우, vite.config.js에서 호스트를 직접 지정할 수 있습니다:

import { defineConfig } from 'vite';

import laravel from 'laravel-vite-plugin';

export default defineConfig({

    plugins: [

        laravel({

            // ...

            detectTls: 'my-app.test', //

}),

],

});

다른 웹 서버를 사용하는 경우에는 신뢰할 수 있는 인증서를 직접 생성하고, Vite가 해당 인증서를 사용하도록 수동으로 설정해야 합니다:

// ...

import fs from 'fs'; //

const host = 'my-app.test'; //

export default defineConfig({

    // ...

    server: { //

        host, //

        hmr: { host }, //

        https: { //

            key: fs.readFileSync(`/path/to/${host}.key`), //

            cert: fs.readFileSync(`/path/to/${host}.crt`), //

        }, //

    }, //

});

시스템에서 신뢰할 수 있는 인증서를 생성할 수 없다면 @vitejs/plugin-basic-ssl 플러그인을 설치하고 설정할 수 있습니다. 신뢰할 수 없는 인증서를 사용할 때는 npm run dev 실행 후 콘솔에 표시되는 "Local" 링크를 브라우저에서 열어 인증서 경고를 수동으로 수락해야 합니다.

WSL2의 Sail에서 개발 서버 실행하기

Windows Subsystem for Linux 2(WSL2) 환경의 Laravel Sail에서 Vite 개발 서버를 실행할 때는 브라우저와 개발 서버 간의 통신을 위해 vite.config.js에 다음 설정을 추가해야 합니다:

// ...

export default defineConfig({
    // ...
    server: { // [tl! add:start]
        hmr: {
            host: 'localhost',
        },
    }, // [tl! add:end]
});

개발 서버가 실행 중임에도 파일 변경 사항이 브라우저에 반영되지 않는다면 Vite의 server.watch.usePolling 옵션도 설정해 보세요.

스크립트와 스타일 로드하기

Vite 엔트리 포인트를 설정했다면, 애플리케이션의 루트 템플릿 <head> 안에 @vite() Blade 디렉티브를 추가하여 에셋을 로드할 수 있습니다:

<!DOCTYPE html>
<head>
    {{-- ... --}}

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

CSS를 JavaScript에서 import하는 경우에는 JavaScript 엔트리 포인트만 지정해도 됩니다:

<!DOCTYPE html>
<head>
    {{-- ... --}}

    @vite('resources/js/app.js')
</head>

@vite 디렉티브는 Vite 개발 서버를 자동으로 감지하여 HMR(Hot Module Replacement)을 위한 Vite 클라이언트를 주입합니다. 프로덕션 빌드 모드에서는 import된 CSS를 포함하여 컴파일되고 버전 처리된 에셋을 로드합니다.

필요하다면 @vite 디렉티브 호출 시 빌드 경로를 직접 지정할 수도 있습니다:

<!doctype html>
<head>
    {{-- 빌드 경로는 public 경로를 기준으로 하는 상대 경로입니다. --}}

    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

인라인 에셋

에셋의 버전 처리된 URL을 링크로 연결하는 대신, 에셋의 내용을 HTML에 직접 포함해야 하는 경우가 있습니다. 예를 들어 PDF 생성기에 HTML 콘텐츠를 전달할 때 에셋 내용을 페이지에 직접 삽입해야 할 수 있습니다. 이럴 때는 Vite 파사드의 content 메서드를 사용하세요:

@use('Illuminate\Support\Facades\Vite')

<!doctype html>
<head>
    {{-- ... --}}

    <style>
        {!! Vite::content('resources/css/app.css') !!}
    </style>
    <script>
        {!! Vite::content('resources/js/app.js') !!}
    </script>
</head>

Vite 실행하기

Vite를 실행하는 방법은 두 가지입니다. 로컬 개발 시에는 dev 명령으로 개발 서버를 실행합니다. 개발 서버는 파일 변경을 자동으로 감지하여 열려 있는 브라우저 창에 즉시 반영합니다.

프로덕션 배포를 위해서는 build 명령으로 에셋을 번들링하고 버전 처리합니다:

# Vite 개발 서버 실행npm run dev# 프로덕션 배포를 위한 에셋 빌드 및 버전 처리npm run build

WSL2의 Sail에서 개발 서버를 실행하는 경우 추가 설정이 필요할 수 있습니다.

JavaScript 작업

별칭(Alias)

Laravel 플러그인은 기본적으로 자주 사용되는 경로에 대한 별칭을 제공합니다:

{
    '@' => '/resources/js'
}

'@' 별칭을 다른 경로로 재정의하려면 vite.config.js에 직접 추가하면 됩니다:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel(['resources/ts/app.tsx']),
    ],
    resolve: {
        alias: {
            '@': '/resources/ts',
        },
    },
});

Vue

Vue 프레임워크로 프론트엔드를 개발하려면 @vitejs/plugin-vue 플러그인을 추가로 설치해야 합니다:

npm install --save-dev @vitejs/plugin-vue

이후 vite.config.js에 플러그인을 추가합니다. Laravel에서 Vue 플러그인을 사용할 때는 몇 가지 추가 옵션이 필요합니다:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    // Vue 플러그인은 Single File Component에서 참조된 에셋 URL을
                    // Laravel 웹 서버를 가리키도록 재작성합니다.
                    // null로 설정하면 Laravel 플러그인이 에셋 URL을
                    // Vite 서버를 가리키도록 재작성합니다.
                    base: null,

                    // Vue 플러그인은 절대 경로 URL을 디스크의 절대 경로로 처리합니다.
                    // false로 설정하면 절대 경로 URL을 그대로 유지하여
                    // public 디렉터리의 에셋을 예상대로 참조할 수 있습니다.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

NOTE

Laravel의 스타터 킷에는 Laravel, Vue, Vite 설정이 이미 포함되어 있습니다. Laravel Breeze를 사용하면 Laravel, Vue, Vite를 가장 빠르게 시작할 수 있습니다.

React

React 프레임워크로 프론트엔드를 개발하려면 @vitejs/plugin-react 플러그인을 추가로 설치해야 합니다:

npm install --save-dev @vitejs/plugin-react

이후 vite.config.js에 플러그인을 추가합니다:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

JSX를 포함하는 파일은 반드시 .jsx 또는 .tsx 확장자를 사용해야 하며, 필요하다면 위에서 설명한 것처럼 엔트리 포인트도 함께 변경하세요.

또한 기존 @vite 디렉티브와 함께 @viteReactRefresh Blade 디렉티브를 추가해야 합니다:

@viteReactRefresh
@vite('resources/js/app.jsx')

@viteReactRefresh 디렉티브는 반드시 @vite 디렉티브 앞에 위치해야 합니다.

NOTE

Laravel의 스타터 킷에는 Laravel, React, Vite 설정이 이미 포함되어 있습니다. Laravel Breeze를 사용하면 Laravel, React, Vite를 가장 빠르게 시작할 수 있습니다.

Inertia

Laravel Vite 플러그인은 Inertia 페이지 컴포넌트를 편리하게 resolve할 수 있는 resolvePageComponent 함수를 제공합니다. 아래는 Vue 3에서 사용하는 예시이며, React 등 다른 프레임워크에서도 동일하게 활용할 수 있습니다:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
});

Inertia에서 Vite의 코드 스플리팅 기능을 사용한다면 에셋 프리페치 설정을 함께 활용하는 것을 권장합니다.

NOTE

Laravel의 스타터 킷에는 Laravel, Inertia, Vite 설정이 이미 포함되어 있습니다. Laravel Breeze를 사용하면 Laravel, Inertia, Vite를 가장 빠르게 시작할 수 있습니다.

URL 처리

Vite를 사용하면서 HTML, CSS, JS에서 에셋을 참조할 때 몇 가지 주의 사항이 있습니다.

절대 경로로 에셋을 참조하면 Vite가 해당 에셋을 빌드에 포함하지 않습니다. 따라서 해당 에셋이 public 디렉터리에 있어야 합니다. 또한 별도 CSS 엔트리 포인트를 사용할 때 절대 경로 사용을 피하세요. 개발 중 브라우저가 CSS가 호스팅된 Vite 개발 서버가 아닌 public 디렉터리에서 해당 경로를 로드하려고 시도하기 때문입니다.

상대 경로로 에셋을 참조할 때는 경로가 참조하는 파일 기준으로 해석됩니다. 상대 경로로 참조된 에셋은 Vite가 자동으로 재작성하고 버전 처리 및 번들링합니다.

예를 들어 다음과 같은 프로젝트 구조를 가정해 보겠습니다:

public/
  taylor.png
resources/
  js/
    Pages/
      Welcome.vue
  images/
    abigail.png

Vite가 상대 경로와 절대 경로를 어떻게 처리하는지 확인해 보세요:

<!-- Vite가 처리하지 않으며 빌드에 포함되지 않습니다 -->
<img src="/taylor.png">

<!-- Vite가 재작성하고 버전 처리 및 번들링합니다 -->
<img src="../../images/abigail.png">

스타일시트 작업

Vite의 CSS 지원에 대한 자세한 내용은 Vite 공식 문서를 참고하세요. Tailwind와 같은 PostCSS 플러그인을 사용한다면 프로젝트 루트에 postcss.config.js 파일을 만들면 Vite가 자동으로 이를 적용합니다:

export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

NOTE

Laravel의 스타터 킷에는 Tailwind, PostCSS, Vite 설정이 이미 포함되어 있습니다. 스타터 킷 없이 Tailwind와 Laravel을 함께 사용하려면 Tailwind의 Laravel 설치 가이드를 참고하세요.

Blade 및 라우트 작업

Vite로 정적 에셋 처리하기

JavaScript나 CSS에서 에셋을 참조하면 Vite가 자동으로 처리하고 버전을 지정합니다. Blade 기반 애플리케이션을 빌드할 때 Vite는 Blade 템플릿에서만 참조하는 정적 에셋도 처리하고 버전을 지정할 수 있습니다.

단, 이를 위해서는 Vite가 해당 에셋을 인식할 수 있도록 애플리케이션의 엔트리 포인트에서 정적 에셋을 import해야 합니다. 예를 들어 resources/images의 모든 이미지와 resources/fonts의 모든 폰트를 처리하고 버전을 지정하려면 resources/js/app.js 엔트리 포인트에 다음을 추가하세요:

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

이후 npm run build를 실행하면 Vite가 이 에셋들을 처리합니다. Blade 템플릿에서는 Vite::asset 메서드를 사용해 버전 처리된 URL을 가져올 수 있습니다:

<img src="{{ Vite::asset('resources/images/logo.png') }}">

저장 시 자동 새로고침

Blade를 사용하는 전통적인 서버 사이드 렌더링 방식의 애플리케이션에서는 Vite의 자동 새로고침 기능으로 개발 생산성을 높일 수 있습니다. refresh 옵션을 true로 설정하면 뷰 파일을 저장할 때마다 브라우저가 자동으로 새로고침됩니다:

import { defineConfig } from 'vite';
import laravel from 'laravel