Skip to content
Laravel

에셋 번들링 (Vite)

소개

Vite는 매우 빠른 개발 환경을 제공하고 프로덕션용으로 코드를 번들링하는 최신 프런트엔드 빌드 도구입니다. Laravel로 애플리케이션을 구축할 때 일반적으로 Vite를 사용하여 애플리케이션의 CSS 및 JavaScript 파일을 프로덕션 준비된 에셋으로 번들링합니다.

Laravel은 개발 및 프로덕션용 에셋을 로드하기 위한 공식 플러그인과 Blade 지시문을 제공하여 Vite와 원활하게 통합됩니다.

lightbulb

Laravel Mix를 사용하고 계십니까? Vite는 새로운 Laravel 설치에서 Laravel Mix를 대체했습니다. Mix 문서에 대해서는 Laravel Mix 웹사이트를 방문하십시오. Vite로 전환하려면 마이그레이션 가이드를 참조하십시오.

Vite와 Laravel Mix 중 선택

Vite로 전환하기 전에 새로운 Laravel 애플리케이션은 에셋을 번들링할 때 webpack으로 구동되는 Mix를 활용했습니다. Vite는 풍부한 JavaScript 애플리케이션을 구축할 때 더 빠르고 생산적인 경험을 제공하는 데 중점을 둡니다. Inertia와 같은 도구로 개발된 것을 포함하여 단일 페이지 애플리케이션 (SPA)을 개발하는 경우 Vite가 완벽하게 적합합니다.

Vite는 Livewire를 사용하는 것을 포함하여 JavaScript "스프링클"이 있는 기존 서버 측 렌더링 애플리케이션에서도 잘 작동합니다. 그러나 JavaScript 애플리케이션에서 직접 참조되지 않은 임의의 에셋을 빌드로 복사하는 기능과 같이 Laravel Mix가 지원하는 일부 기능이 부족합니다.

Mix로 다시 마이그레이션

Vite 스캐폴딩을 사용하여 새로운 Laravel 애플리케이션을 시작했지만 Laravel Mix 및 webpack으로 다시 이동해야 합니까? 문제 없습니다. Vite에서 Mix로 마이그레이션하는 방법에 대한 공식 가이드를 참조하십시오.

설치 및 설정

lightbulb

다음 문서는 Laravel Vite 플러그인을 수동으로 설치하고 구성하는 방법을 설명합니다. 그러나 Laravel의 스타터 키트에는 이미 이 모든 스캐폴딩이 포함되어 있으며 Laravel 및 Vite를 시작하는 가장 빠른 방법입니다.

Node 설치

Vite 및 Laravel 플러그인을 실행하기 전에 Node.js (16+) 및 NPM이 설치되어 있는지 확인해야 합니다.

node -v
npm -v

공식 Node 웹사이트에서 간단한 그래픽 설치 프로그램을 사용하여 최신 버전의 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를 빌드하는 경우 Vite는 CSS 진입점 없이 가장 잘 작동합니다:

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

대신, JavaScript를 통해 CSS를 가져와야 합니다. 일반적으로 애플리케이션의 resources/js/app.js 파일에서 다음과 같이 수행합니다.

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

Laravel 플러그인은 또한 여러 진입점과 SSR 진입점과 같은 고급 구성 옵션을 지원합니다.

보안 개발 서버 사용하기

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

Laravel Herd를 사용하고 사이트를 보호했거나 Laravel Valet을 사용하고 애플리케이션에 대해 보안 명령을 실행한 경우 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" 링크를 따라 브라우저에서 Vite 개발 서버에 대한 인증서 경고를 수락해야 합니다.

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

Windows Subsystem for Linux 2 (WSL2)에서 Laravel Sail 내에서 Vite 개발 서버를 실행하는 경우, 브라우저가 개발 서버와 통신할 수 있도록 하려면 vite.config.js 파일에 다음 구성을 추가해야 합니다.

// ...
 
export default defineConfig({
    // ...
    server: { 
        hmr: {
            host: 'localhost',
        },
    }, 
});

개발 서버가 실행되는 동안 파일 변경 사항이 브라우저에 반영되지 않는 경우, Vite의 server.watch.usePolling 옵션을 구성해야 할 수도 있습니다.

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

Vite 진입점이 구성되었으므로 이제 애플리케이션의 루트 템플릿의 <head>에 추가하는 @vite() Blade 지시문에서 해당 진입점을 참조할 수 있습니다.

<!DOCTYPE html>
<head>
    {{-- ... --}}
 
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

JavaScript를 통해 CSS를 가져오는 경우, JavaScript 진입점만 포함하면 됩니다.

<!DOCTYPE html>
<head>
    {{-- ... --}}
 
    @vite('resources/js/app.js')
</head>

@vite 지시어는 Vite 개발 서버를 자동으로 감지하고 Hot Module Replacement를 활성화하기 위해 Vite 클라이언트를 삽입합니다. 빌드 모드에서 이 지시어는 가져온 CSS를 포함하여 컴파일되고 버전이 지정된 자산을 로드합니다.

필요한 경우 @vite 지시어를 호출할 때 컴파일된 자산의 빌드 경로를 지정할 수도 있습니다:

<!doctype html>
<head>
    {{-- 주어진 빌드 경로는 public 경로를 기준으로 합니다. --}}
 
    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

인라인 자산

때로는 자산의 버전이 지정된 URL에 연결하는 대신 자산의 원시 콘텐츠를 포함해야 할 수도 있습니다. 예를 들어, HTML 콘텐츠를 PDF 생성기에 전달할 때 자산 콘텐츠를 페이지에 직접 포함해야 할 수 있습니다. Vite 파사드에서 제공하는 content 메서드를 사용하여 Vite 자산의 콘텐츠를 출력할 수 있습니다:

@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 작업

별칭

기본적으로 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 플러그인은 단일 파일 컴포넌트에서 참조될 때, 에셋 URL을 Laravel 웹 서버를 가리키도록 재작성합니다.
                    // 이 값을 `null`로 설정하면 Laravel 플러그인이 에셋 URL을 Vite 서버를 가리키도록 대신 재작성할 수 있습니다.
                    base: null,
 
                    // Vue 플러그인은 절대 URL을 파싱하고 디스크의 파일에 대한 절대 경로로 처리합니다.
                    // 이 값을 `false`로 설정하면 절대 URL을 그대로 두어 예상대로 public 디렉터리의 에셋을 참조할 수 있습니다.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});
lightbulb

Laravel의 스타터 키트에는 이미 적절한 Laravel, Vue 및 Vite 구성이 포함되어 있습니다. Laravel, Vue 및 Vite를 사용하여 가장 빠르게 시작하려면 Laravel Breeze를 확인하십시오.

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 지시문 앞에 호출해야 합니다.

lightbulb

Laravel의 스타터 키트에는 이미 올바른 Laravel, React 및 Vite 구성이 포함되어 있습니다. Laravel, React 및 Vite를 가장 빠르게 시작하려면 Laravel Breeze를 확인해 보세요.

Inertia

Laravel Vite 플러그인은 Inertia 페이지 컴포넌트를 해결하는 데 도움이 되는 편리한 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의 코드 분할 기능을 사용하는 경우, 애셋 프리패칭을 구성하는 것을 권장합니다.

lightbulb

Laravel의 스타터 키트에는 이미 적절한 Laravel, Inertia 및 Vite 구성이 포함되어 있습니다. Laravel, Inertia 및 Vite를 가장 빠르게 시작하는 방법은 Laravel Breeze를 확인해 보세요.

URL 처리

Vite를 사용하고 애플리케이션의 HTML, CSS 또는 JS에서 애셋을 참조할 때 고려해야 할 몇 가지 주의 사항이 있습니다. 첫째, 절대 경로로 애셋을 참조하면 Vite는 빌드에 해당 애셋을 포함하지 않습니다. 따라서 해당 애셋이 public 디렉터리에 있는지 확인해야 합니다. 전용 CSS 진입점을 사용할 때는 절대 경로를 사용하지 않는 것이 좋습니다. 개발 중에 브라우저가 public 디렉터리가 아닌 CSS가 호스팅되는 Vite 개발 서버에서 이러한 경로를 로드하려고 하기 때문입니다.

상대 애셋 경로를 참조할 때, 경로는 참조되는 파일에 상대적이라는 점을 기억해야 합니다. 상대 경로를 통해 참조된 모든 애셋은 Vite에 의해 재작성, 버전 관리 및 번들링됩니다.

다음 프로젝트 구조를 고려하십시오.

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

다음 예는 Vite가 상대 및 절대 URL을 처리하는 방법을 보여줍니다.

<!-- 이 애셋은 Vite에서 처리되지 않으며 빌드에 포함되지 않습니다. -->
<img src="/taylor.png">
 
<!-- 이 애셋은 Vite에 의해 재작성, 버전 관리 및 번들링됩니다. -->
<img src="../../images/abigail.png">

스타일시트 작업

Vite 문서에서 Vite의 CSS 지원에 대해 자세히 알아볼 수 있습니다. Tailwind와 같은 PostCSS 플러그인을 사용하는 경우 프로젝트 루트에 postcss.config.js 파일을 생성하면 Vite에서 자동으로 적용합니다.

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

Laravel의 starter kit에는 이미 적절한 Tailwind, PostCSS 및 Vite 구성이 포함되어 있습니다. 또는 starter kit을 사용하지 않고 Tailwind와 Laravel을 사용하려면 Laravel용 Tailwind 설치 가이드를 확인하세요.

Blade 및 라우트 작업

Vite를 사용하여 정적 자산 처리

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

그러나 이를 위해서는 애플리케이션의 진입점에 정적 자산을 가져와 Vite가 자산을 인식하도록 해야 합니다. 예를 들어 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-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: true,
        }),
    ],
});

refresh 옵션이 true일 때, npm run dev를 실행하는 동안 다음 디렉토리의 파일을 저장하면 브라우저에서 전체 페이지 새로 고침을 수행합니다.

  • app/Livewire/**
  • app/View/Components/**
  • lang/**
  • resources/lang/**
  • resources/views/**
  • routes/**

애플리케이션의 프런트엔드 내에서 라우트 링크를 생성하기 위해 Ziggy를 사용하는 경우 routes/** 디렉토리를 감시하는 것이 유용합니다.

이러한 기본 경로가 필요에 맞지 않으면 감시할 경로 목록을 직접 지정할 수 있습니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: ['resources/views/**'],
        }),
    ],
});

내부적으로 Laravel Vite 플러그인은 vite-plugin-full-reload 패키지를 사용하며, 이 패키지는 이 기능의 동작을 미세 조정하기 위한 몇 가지 고급 구성 옵션을 제공합니다. 이 수준의 사용자 정의가 필요한 경우 config 정의를 제공할 수 있습니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: [{
                paths: ['path/to/watch/**'],
                config: { delay: 300 }
            }],
        }),
    ],
});

별칭 (Aliases)

JavaScript 애플리케이션에서 자주 참조되는 디렉토리에 대한 별칭을 만드는 것은 일반적입니다. 그러나 Illuminate\Support\Facades\Vite 클래스의 macro 메서드를 사용하여 Blade에서 사용할 별칭을 만들 수도 있습니다. 일반적으로 "매크로"는 서비스 제공자의 boot 메서드 내에서 정의되어야 합니다.

/**
 * 애플리케이션 서비스 부트스트랩.
 */
public function boot(): void
{
    Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
}

매크로가 정의되면 템플릿 내에서 호출할 수 있습니다. 예를 들어, 위에서 정의된 image 매크로를 사용하여 resources/images/logo.png에 있는 에셋을 참조할 수 있습니다.

<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">

에셋 미리 가져오기 (Asset Prefetching)

Vite의 코드 분할 기능을 사용하여 SPA를 구축할 때, 필요한 에셋은 각 페이지 탐색 시에 가져옵니다. 이 동작은 UI 렌더링 지연으로 이어질 수 있습니다. 만약 이것이 선택한 프론트엔드 프레임워크에 문제가 된다면, Laravel은 초기 페이지 로드 시에 애플리케이션의 JavaScript 및 CSS 에셋을 미리 가져올 수 있는 기능을 제공합니다.

서비스 제공자의 boot 메서드에서 Vite::prefetch 메서드를 호출하여 Laravel에 에셋을 미리 가져오도록 지시할 수 있습니다.

<?php
 
namespace App\Providers;
 
use Illuminate\Support\Facades\Vite;
use Illuminate\Support\ServiceProvider;
 
class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        // ...
    }
 
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Vite::prefetch(concurrency: 3);
    }
}

위 예시에서, 에셋은 각 페이지 로드 시 최대 3개의 동시 다운로드로 프리페치됩니다. 애플리케이션의 요구 사항에 맞게 동시성을 수정하거나, 애플리케이션이 모든 에셋을 한 번에 다운로드해야 하는 경우 동시성 제한을 지정하지 않을 수 있습니다:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::prefetch();
}

기본적으로 프리페치는 페이지 로드 이벤트가 발생할 때 시작됩니다. 프리페치가 시작되는 시점을 사용자 지정하려면 Vite가 수신할 이벤트를 지정할 수 있습니다:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::prefetch(event: 'vite:prefetch');
}

위 코드가 주어지면, 이제 window 객체에서 vite:prefetch 이벤트를 수동으로 디스패치할 때 프리페치가 시작됩니다. 예를 들어, 페이지가 로드된 후 3초 후에 프리페치가 시작되도록 할 수 있습니다:

<script>
    addEventListener('load', () => setTimeout(() => {
        dispatchEvent(new Event('vite:prefetch'))
    }, 3000))
</script>

사용자 지정 기본 URL

Vite로 컴파일된 에셋이 애플리케이션과 별도의 도메인(예: CDN)에 배포된 경우, 애플리케이션의 .env 파일 내에서 ASSET_URL 환경 변수를 지정해야 합니다:

ASSET_URL=https://cdn.example.com

에셋 URL을 구성한 후에는 에셋에 대한 모든 재작성된 URL이 구성된 값으로 접두사가 붙습니다:

https://cdn.example.com/build/assets/app.9dce8d17.js

절대 URL은 Vite에 의해 재작성되지 않으므로 접두사가 붙지 않습니다.

환경 변수

애플리케이션의 .env 파일에서 VITE_ 접두사를 사용하여 JavaScript에 환경 변수를 주입할 수 있습니다:

VITE_SENTRY_DSN_PUBLIC=http://example.com

import.meta.env 객체를 통해 주입된 환경 변수에 접근할 수 있습니다:

import.meta.env.VITE_SENTRY_DSN_PUBLIC

테스트에서 Vite 비활성화

Laravel의 Vite 통합은 테스트를 실행하는 동안 에셋을 확인하려고 시도하며, 이로 인해 Vite 개발 서버를 실행하거나 에셋을 빌드해야 합니다.

테스트 중에 Vite를 모의로 처리하고 싶다면 Laravel의 TestCase 클래스를 확장하는 모든 테스트에 사용할 수 있는 withoutVite 메서드를 호출하면 됩니다:

test('vite 예제 없이', function () {
    $this->withoutVite();
 
    // ...
});
use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    public function test_without_vite_example(): void
    {
        $this->withoutVite();
 
        // ...
    }
}

모든 테스트에서 Vite를 비활성화하고 싶다면 기본 TestCase 클래스의 setUp 메서드에서 withoutVite 메서드를 호출할 수 있습니다:

<?php
 
namespace Tests;
 
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
 
abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();
 
        $this->withoutVite();
    }
}

서버 사이드 렌더링(SSR)

Laravel Vite 플러그인을 사용하면 Vite를 사용하여 서버 사이드 렌더링을 쉽게 설정할 수 있습니다. 시작하려면 resources/js/ssr.js에 SSR 진입점을 만들고 Laravel 플러그인에 구성 옵션을 전달하여 진입점을 지정하십시오:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            ssr: 'resources/js/ssr.js',
        }),
    ],
});

SSR 진입점을 다시 빌드하는 것을 잊지 않도록 애플리케이션의 package.json에서 "build" 스크립트를 수정하여 SSR 빌드를 생성하는 것이 좋습니다.

"scripts": {
     "dev": "vite",
     "build": "vite build" 
     "build": "vite build && vite build --ssr" 
}

그런 다음, SSR 서버를 빌드하고 시작하려면 다음 명령을 실행하면 됩니다.

npm run build
node bootstrap/ssr/ssr.js

Inertia와 함께 SSR을 사용하는 경우 대신 inertia:start-ssr Artisan 명령을 사용하여 SSR 서버를 시작할 수 있습니다.

php artisan inertia:start-ssr
lightbulb

Laravel의 스타터 키트에는 이미 적절한 Laravel, Inertia SSR 및 Vite 구성이 포함되어 있습니다. Laravel, Inertia SSR 및 Vite를 가장 빠르게 시작하려면 Laravel Breeze를 확인하세요.

스크립트 및 스타일 태그 속성

콘텐츠 보안 정책 (CSP) Nonce

콘텐츠 보안 정책의 일부로 스크립트 및 스타일 태그에 nonce 속성을 포함하려는 경우, 사용자 정의 미들웨어 내에서 useCspNonce 메서드를 사용하여 nonce를 생성하거나 지정할 수 있습니다.

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Symfony\Component\HttpFoundation\Response;
 
class AddContentSecurityPolicyHeaders
{
    /**
     * 들어오는 요청을 처리합니다.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        Vite::useCspNonce();
 
        return $next($request)->withHeaders([
            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
        ]);
    }
}

useCspNonce 메서드를 호출하면 Laravel은 자동으로 생성된 모든 script 및 style 태그에 nonce 속성을 포함합니다.

Laravel의 스타터 키트에 포함된 Ziggy @route 지시어를 포함하여 다른 곳에서 nonce를 지정해야 하는 경우 cspNonce 메서드를 사용하여 검색할 수 있습니다.

@routes(nonce: Vite::cspNonce())

Laravel에서 사용할 nonce가 이미 있는 경우 useCspNonce 메서드에 nonce를 전달할 수 있습니다.

Vite::useCspNonce($nonce);

하위 리소스 무결성 (SRI)

Vite 매니페스트에 에셋에 대한 integrity 해시가 포함된 경우, Laravel은 하위 리소스 무결성을 적용하기 위해 생성하는 모든 script 및 style 태그에 자동으로 integrity 속성을 추가합니다. 기본적으로 Vite는 매니페스트에 integrity 해시를 포함하지 않지만 vite-plugin-manifest-sri NPM 플러그인을 설치하여 활성화할 수 있습니다.

npm install --save-dev vite-plugin-manifest-sri

그런 다음 vite.config.js 파일에서 이 플러그인을 활성화할 수 있습니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import manifestSRI from 'vite-plugin-manifest-sri';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
        }),
        manifestSRI(),
    ],
});

필요한 경우, 무결성 해시를 찾을 수 있는 매니페스트 키를 사용자 정의할 수도 있습니다.

use Illuminate\Support\Facades\Vite;
 
Vite::useIntegrityKey('custom-integrity-key');

이 자동 감지를 완전히 비활성화하려면 useIntegrityKey 메서드에 false를 전달하면 됩니다.

Vite::useIntegrityKey(false);

임의의 속성

스크립트 및 스타일 태그에 data-turbo-track 속성과 같은 추가 속성을 포함해야 하는 경우 useScriptTagAttributes 및 useStyleTagAttributes 메서드를 통해 지정할 수 있습니다. 일반적으로 이 메서드는 서비스 제공자에서 호출해야 합니다.

use Illuminate\Support\Facades\Vite;
 
Vite::useScriptTagAttributes([
    'data-turbo-track' => 'reload', // 속성 값을 지정합니다...
    'async' => true, // 값 없이 속성을 지정합니다...
    'integrity' => false, // 그렇지 않으면 포함될 속성을 제외합니다...
]);
 
Vite::useStyleTagAttributes([
    'data-turbo-track' => 'reload',
]);

조건부로 속성을 추가해야 하는 경우, 자산 소스 경로, 해당 URL, 매니페스트 청크 및 전체 매니페스트를 수신하는 콜백을 전달할 수 있습니다.

use Illuminate\Support\Facades\Vite;
 
Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
]);
 
Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
]);
exclamation

$chunk 및 $manifest 인수는 Vite 개발 서버가 실행 중인 동안 null이 됩니다.

고급 사용자 정의

기본적으로 Laravel의 Vite 플러그인은 대부분의 애플리케이션에서 작동해야 하는 합리적인 규칙을 사용합니다. 그러나 때로는 Vite의 동작을 사용자 정의해야 할 수도 있습니다. 추가 사용자 정의 옵션을 활성화하기 위해 @vite Blade 지시문 대신 사용할 수 있는 다음 메서드와 옵션을 제공합니다.

<!doctype html>
<head>
    {{-- ... --}}
 
    {{
        Vite::useHotFile(storage_path('vite.hot')) // "hot" 파일 사용자 정의...
            ->useBuildDirectory('bundle') // 빌드 디렉토리 사용자 정의...
            ->useManifestFilename('assets.json') // 매니페스트 파일 이름 사용자 정의...
            ->withEntryPoints(['resources/js/app.js']) // 엔트리 포인트 지정...
            ->createAssetPathsUsing(function (string $path, ?bool $secure) { // 빌드된 에셋에 대한 백엔드 경로 생성 사용자 정의...
                return "https://cdn.example.com/{$path}";
            })
    }}
</head>

vite.config.js 파일 내에서 동일한 구성을 지정해야 합니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot', // "hot" 파일 사용자 정의...
            buildDirectory: 'bundle', // 빌드 디렉토리 사용자 정의...
            input: ['resources/js/app.js'], // 진입점 지정...
        }),
    ],
    build: {
      manifest: 'assets.json', // 매니페스트 파일명 사용자 정의...
    },
});

개발 서버 URL 수정하기

Vite 생태계 내 일부 플러그인은 슬래시(/)로 시작하는 URL이 항상 Vite 개발 서버를 가리킨다고 가정합니다. 그러나 Laravel 통합의 특성상 이는 사실이 아닙니다.

예를 들어, vite-imagetools 플러그인은 Vite가 에셋을 제공하는 동안 다음과 같은 URL을 출력합니다.

<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

vite-imagetools 플러그인은 출력 URL이 Vite에 의해 가로채지고 플러그인이 /@imagetools로 시작하는 모든 URL을 처리할 수 있을 것으로 예상합니다. 이러한 동작을 기대하는 플러그인을 사용하는 경우 URL을 수동으로 수정해야 합니다. vite.config.js 파일에서 transformOnServe 옵션을 사용하여 이를 수행할 수 있습니다.

이 특정 예에서는 생성된 코드 내에서 /@imagetools의 모든 발생에 개발 서버 URL을 추가합니다.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { imagetools } from 'vite-imagetools';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
        }),
        imagetools(),
    ],
});

이제 Vite가 에셋을 제공하는 동안 Vite 개발 서버를 가리키는 URL을 출력합니다.

- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">