프론트엔드(Vite)

업데이트됨

번역일: 2026년 6월 21일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 21일

프론트엔드(Vite)

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

소개

Vite는 빠른 개발 환경과 프로덕션 번들링을 지원하는 현대적인 프론트엔드 빌드 도구입니다. Laravel로 애플리케이션을 개발할 때는 보통 Vite를 사용해 CSS와 JavaScript 파일을 프로덕션에 배포할 수 있는 에셋으로 번들링합니다.

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

설치 및 설정

NOTE

아래 문서는 Laravel Vite 플러그인을 직접 설치하고 설정하는 방법을 설명합니다. 하지만 Laravel의 스타터 킷을 사용하면 이 모든 설정이 이미 포함되어 있으므로, 빠르게 시작하고 싶다면 스타터 킷을 활용하는 것을 권장합니다.

Node 설치

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

node -vnpm -v

Node 공식 사이트에서 최신 버전의 Node와 NPM을 그래픽 설치 프로그램으로 쉽게 설치할 수 있습니다. Laravel Sail을 사용하고 있다면 Sail을 통해 Node와 NPM 명령을 실행할 수도 있습니다:

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

Vite와 Laravel 플러그인 설치

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

npm install

Vite 설정

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

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 포함)을 로드합니다.

빌드된 에셋의 경로를 직접 지정해야 하는 경우에는 두 번째 인수로 경로를 전달할 수 있습니다:

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

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

인라인 에셋

PDF 생성기에 HTML을 전달하는 경우처럼, 에셋의 버전 관리된 URL 대신 파일 내용을 직접 페이지에 포함해야 할 때도 있습니다. 이런 경우 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 다루기

경로 별칭(Aliases)

Laravel 플러그인은 기본적으로 다음 별칭을 제공해 에셋 경로를 편리하게 참조할 수 있습니다:

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

vite.config.js에 직접 resolve.alias 설정을 추가해 '@' 별칭을 덮어쓸 수 있습니다:

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 플러그인은 SFC(Single File Components)에서 참조된
                    // 에셋 URL을 Laravel 웹 서버를 가리키도록 재작성합니다.
                    // null로 설정하면 Laravel 플러그인이 에셋 URL을
                    // Vite 서버를 가리키도록 재작성합니다.
                    base: null,

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

NOTE

Laravel의 스타터 킷에는 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 설정이 이미 포함되어 있습니다. 빠르게 시작하고 싶다면 스타터 킷을 활용하세요.

Svelte

Svelte 프레임워크로 프론트엔드를 개발하려면 @sveltejs/vite-plugin-svelte 플러그인을 설치해야 합니다:

npm install --save-dev @sveltejs/vite-plugin-svelte

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

import { svelte } from '@sveltejs/vite-plugin-svelte';
import laravel from 'laravel-vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      ssr: 'resources/js/ssr.ts',
      refresh: true,
    }),
    svelte(),
  ],
});

NOTE

Laravel의 스타터 킷에는 Laravel, Svelte, Vite 설정이 이미 포함되어 있습니다. 빠르게 시작하고 싶다면 스타터 킷을 활용하세요.

Inertia

Laravel Vite 플러그인은 Inertia 페이지 컴포넌트를 resolve하는 데 도움이 되는 resolvePageComponent 함수를 제공합니다. 아래는 Vue 3와 함께 사용하는 예시이며, React나 Svelte에서도 동일하게 활용할 수 있습니다:

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)
  },
});

Vite의 코드 스플리팅 기능을 Inertia와 함께 사용한다면 에셋 프리페칭 설정을 권장합니다.

NOTE

Laravel의 스타터 킷에는 Laravel, Inertia, Vite 설정이 이미 포함되어 있습니다. 빠르게 시작하고 싶다면 스타터 킷을 활용하세요.

URL 처리

Vite를 사용할 때 HTML, CSS, JS에서 에셋을 참조하는 방식에 따라 동작이 달라집니다. 먼저, 절대 경로로 에셋을 참조하면 Vite가 빌드에 포함하지 않습니다. 따라서 해당 에셋이 public 디렉터리에 있는지 확인해야 합니다. 또한 독립된 CSS 엔트리 포인트를 사용하는 경우 절대 경로 사용을 피하세요. 개발 중에 브라우저가 해당 경로를 public 디렉터리가 아닌 Vite 개발 서버에서 로드하려 하기 때문입니다.

상대 경로로 에셋을 참조하면, 해당 경로는 파일이 위치한 곳을 기준으로 처리됩니다. 상대 경로로 참조된 에셋은 Vite가 자동으로 재작성하고 버전 관리하며 번들링합니다.

다음 프로젝트 구조를 예시로 살펴봅시다:

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

아래 예시는 Vite가 상대 경로와 절대 경로를 어떻게 처리하는지 보여줍니다:

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

<!-- 이 에셋은 Vite가 재작성, 버전 관리, 번들링합니다 -->
<img src="../../images/abigail.png">

스타일시트 다루기

NOTE

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

모든 Laravel 애플리케이션에는 Tailwind와 올바르게 설정된 vite.config.js가 포함되어 있습니다. Vite 개발 서버를 시작하거나, Laravel과 Vite 개발 서버를 함께 시작하는 dev Composer 명령을 실행하기만 하면 됩니다:

composer run dev

애플리케이션의 CSS는 resources/css/app.css 파일에 작성합니다.

폰트 다루기

Laravel Vite 플러그인은 최적화된 셀프 호스팅 폰트를 제공할 수 있습니다. 폰트를 설정하면 플러그인이 폰트 파일을 resolve하고 Vite 에셋으로 내보내며, 폰트 CSS를 생성하고 Blade의 @fonts 디렉티브가 사용할 수 있는 폰트 매니페스트를 작성합니다.

폰트를 설정하려면 laravel-vite-plugin/fonts에서 프로바이더 헬퍼를 import하고 Laravel 플러그인의 fonts 옵션에 추가합니다:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { google } from 'laravel-vite-plugin/fonts';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            fonts: [
                google('Inter', {
                    alias: 'sans',
                    weights: [400, 500, 600, 700],
                    styles: ['normal', 'italic'],
                    subsets: ['latin'],
                    display: 'swap',
                    preload: [
                        { weight: 400 },
                        { weight: 700 },
                    ],
                    fallbacks: ['system-ui', 'sans-serif'],
                }),
            ],
        }),
    ],
});

이 예시에서 Inter 폰트는 sans 별칭으로 사용할 수 있습니다. 플러그인은 --font-sans CSS 변수와 생성된 폰트 스택을 적용하는 .font-sans 유틸리티 클래스를 자동으로 생성합니다.

폰트 프로바이더

Laravel Vite 플러그인은 Google Fonts, Bunny Fonts, Fontsource, 로컬 폰트를 위한 프로바이더 헬퍼를 제공합니다:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { bunny, fontsource, google, local } from 'laravel-vite-plugin/fonts';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            fonts: [
                google('Inter', { alias: 'sans' }),
                bunny('Figtree', { alias: 'body' }),
                fontsource('JetBrains Mono', { alias: 'mono' }),
                local('Brand Sans', {
                    alias: 'brand',
                    src: 'resources/fonts/brand-sans',
                }),
            ],
        }),
    ],
});

fontsource 프로바이더는 설치된 Fontsource 패키지에서 폰트를 읽습니다. 기본적으로 패키지명은 폰트 패밀리에서 파생되며(예: @fontsource/jetbrains-mono), 다른 패키지명을 사용하는 경우 package 옵션으로 직접 지정할 수 있습니다.

로컬 폰트

로컬 폰트를 사용할 때 src 옵션에는 단일 폰트 파일, 디렉터리, 또는 글로브 패턴을 지정할 수 있습니다. 플러그인은 지원되는 폰트 파일을 자동으로 탐색하고 파일명에서 weight와 style