Asset Bundling (Vite)
Introducción
Vite es una herramienta moderna de construcción de frontend que proporciona un entorno de desarrollo extremadamente rápido y agrupa tu código para producción. Al construir aplicaciones con Laravel, normalmente usarás Vite para agrupar los archivos CSS y JavaScript de tu aplicación en activos listos para producción.
Laravel se integra perfectamente con Vite proporcionando un plugin oficial y una directiva Blade para cargar tus activos para desarrollo y producción.
¿Estás usando Laravel Mix? Vite ha reemplazado a Laravel Mix en nuevas instalaciones de Laravel. Para la documentación de Mix, visita el sitio web de Laravel Mix. Si deseas cambiar a Vite, consulta nuestra guía de migración.
Elegir Entre Vite y Laravel Mix
Antes de la transición a Vite, las nuevas aplicaciones de Laravel utilizaban Mix, que está impulsado por webpack, al agrupar activos. Vite se enfoca en proporcionar una experiencia más rápida y productiva al construir aplicaciones ricas en JavaScript. Si estás desarrollando una Aplicación de Página Única (SPA), incluidas aquellas desarrolladas con herramientas como Inertia, Vite será la opción perfecta.
Vite también funciona bien con aplicaciones renderizadas en el servidor de manera tradicional con «sprinkles» de JavaScript, incluidas aquellas que usan Livewire. Sin embargo, carece de algunas características que Laravel Mix soporta, como la capacidad de copiar activos arbitrarios en la construcción que no están referenciados directamente en tu aplicación JavaScript.
Migrando de Vuelta a Mix
¿Has comenzado una nueva aplicación de Laravel usando nuestro scaffolding de Vite pero necesitas volver a Laravel Mix y webpack? No hay problema. Consulta nuestra guía oficial sobre cómo migrar de Vite a Mix.
Instalación y Configuración
La siguiente documentación discute cómo instalar y configurar manualmente el plugin de Laravel Vite. Sin embargo, los kits de inicio de Laravel ya incluyen todo este scaffolding y son la forma más rápida de comenzar con Laravel y Vite.
Instalando Node
Debes asegurarte de que Node.js (16+) y NPM estén instalados antes de ejecutar Vite y el plugin de Laravel:
node -v
npm -v
Puedes instalar fácilmente la última versión de Node y NPM usando instaladores gráficos simples desde el sitio web oficial de Node. O, si estás usando Laravel Sail, puedes invocar Node y NPM a través de Sail:
./vendor/bin/sail node -v
./vendor/bin/sail npm -v
Instalando Vite y el Plugin de Laravel
Dentro de una instalación nueva de Laravel, encontrarás un archivo package.json en la raíz de la estructura de directorios de tu aplicación. El archivo package.json predeterminado ya incluye todo lo que necesitas para comenzar a usar Vite y el plugin de Laravel. Puedes instalar las dependencias frontend de tu aplicación a través de NPM:
npm install
Configurando Vite
Vite se configura a través de un archivo vite.config.js en la raíz de tu proyecto. Eres libre de personalizar este archivo según tus necesidades, y también puedes instalar cualquier otro plugin que tu aplicación requiera, como @vitejs/plugin-vue o @vitejs/plugin-react.
El plugin de Laravel Vite requiere que especifiques los puntos de entrada para tu aplicación. Estos pueden ser archivos JavaScript o CSS, e incluyen lenguajes preprocesados como TypeScript, JSX, TSX y Sass.
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel([
'resources/css/app.css',
'resources/js/app.js',
]),
],
});
Si estás construyendo una SPA, incluidas aplicaciones construidas usando Inertia, Vite funciona mejor sin puntos de entrada CSS:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel([
'resources/css/app.css',
'resources/js/app.js',
]),
],
});
En su lugar, debes importar tu CSS a través de JavaScript. Normalmente, esto se haría en el archivo resources/js/app.js de tu aplicación:
import './bootstrap';
import '../css/app.css';
El plugin de Laravel también soporta múltiples puntos de entrada y opciones de configuración avanzada como puntos de entrada SSR.
Trabajando con un Servidor de Desarrollo Seguro
Si tu servidor web de desarrollo local está sirviendo tu aplicación a través de HTTPS, puedes encontrarte con problemas al conectarte al servidor de desarrollo de Vite.
Si estás usando Laravel Herd y has asegurado el sitio o estás usando Laravel Valet y has ejecutado el comando secure contra tu aplicación, el plugin de Laravel Vite detectará automáticamente y usará el certificado TLS generado para ti.
Si aseguraste el sitio usando un host que no coincide con el nombre del directorio de la aplicación, puedes especificar manualmente el host en el archivo vite.config.js de tu aplicación:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
// ...
detectTls: 'my-app.test',
}),
],
});
Al usar otro servidor web, debes generar un certificado de confianza y configurar manualmente Vite para usar los certificados generados:
// ...
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`),
},
},
});
Si no puedes generar un certificado de confianza para tu sistema, puedes instalar y configurar el plugin @vitejs/plugin-basic-ssl. Al usar certificados no confiables, necesitarás aceptar la advertencia de certificado para el servidor de desarrollo de Vite en tu navegador siguiendo el enlace «Local» en tu consola al ejecutar el comando npm run dev.
Ejecutando el Servidor de Desarrollo en Sail en WSL2
Al ejecutar el servidor de desarrollo de Vite dentro de Laravel Sail en Windows Subsystem for Linux 2 (WSL2), debes agregar la siguiente configuración a tu archivo vite.config.js para asegurar que el navegador pueda comunicarse con el servidor de desarrollo:
// ...
export default defineConfig({
// ...
server: {
hmr: {
host: 'localhost',
},
},
});
Si los cambios en tus archivos no se reflejan en el navegador mientras el servidor de desarrollo está en ejecución, también puedes necesitar configurar la opción server.watch.usePolling de Vite.
Cargando Tus Scripts y Estilos
Con tus puntos de entrada de Vite configurados, ahora puedes referenciarlos en una directiva Blade @vite() que agregas al <head> de la plantilla raíz de tu aplicación:
<!DOCTYPE html>
<head>
{{-- ... --}}
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
Si estás importando tu CSS a través de JavaScript, solo necesitas incluir el punto de entrada de JavaScript:
<!DOCTYPE html>
<head>
{{-- ... --}}
@vite('resources/js/app.js')
</head>
La directiva @vite detectará automáticamente el servidor de desarrollo de Vite e inyectará el cliente de Vite para habilitar el Hot Module Replacement. En modo de construcción, la directiva cargará tus activos compilados y versionados, incluidos los CSS importados.
Si es necesario, también puedes especificar la ruta de construcción de tus activos compilados al invocar la directiva @vite:
<!doctype html>
<head>
{{-- La ruta de construcción dada es relativa a la ruta pública. --}}
@vite('resources/js/app.js', 'vendor/courier/build')
</head>
Activos en Línea
A veces puede ser necesario incluir el contenido bruto de los activos en lugar de enlazar a la URL versionada del activo. Por ejemplo, puede que necesites incluir el contenido del activo directamente en tu página al pasar contenido HTML a un generador de PDF. Puedes mostrar el contenido de los activos de Vite usando el método content proporcionado por la fachada 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>
Ejecutando Vite
Hay dos formas de ejecutar Vite. Puedes ejecutar el servidor de desarrollo a través del comando dev, que es útil mientras desarrollas localmente. El servidor de desarrollo detectará automáticamente los cambios en tus archivos y los reflejará instantáneamente en cualquier ventana del navegador abierta.
O, ejecutar el comando build versionará y agrupará los activos de tu aplicación y los preparará para que los despliegues en producción:
# Ejecutar el servidor de desarrollo de Vite...
npm run dev
# Construir y versionar los activos para producción...
npm run build
Si estás ejecutando el servidor de desarrollo en Sail en WSL2, puede que necesites algunas opciones de configuración adicionales.
Trabajando con JavaScript
Aliases
Por defecto, el plugin de Laravel proporciona un alias común para ayudarte a comenzar rápidamente e importar cómodamente los activos de tu aplicación:
{
"@": "/resources/js"
}
Puedes sobrescribir el alias @ agregando el tuyo propio al archivo de configuración 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
Si deseas construir tu frontend usando el framework Vue, entonces también necesitarás instalar el plugin @vitejs/plugin-vue:
npm install --save-dev @vitejs/plugin-vue
Luego puedes incluir el plugin en tu archivo de configuración vite.config.js. Hay algunas opciones adicionales que necesitarás al usar el plugin de Vue con Laravel:
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: {
// El plugin de Vue reescribirá las URLs de los activos, cuando se referencien
// en Componentes de Archivo Único, para apuntar al servidor web de Laravel.
// Establecer esto en `null` permite que el plugin de Laravel
// reescriba las URLs de los activos para apuntar al servidor de Vite.
base: null,
// El plugin de Vue analizará las URLs absolutas y las tratará
// como rutas absolutas a archivos en disco. Establecer esto en
// `false` dejará las URLs absolutas sin tocar para que puedan
// referenciar activos en el directorio público como se espera.
includeAbsolute: false,
},
},
}),
],
});
Los kits de inicio de Laravel ya incluyen la configuración adecuada de Laravel, Vue y Vite. Consulta Laravel Breeze para la forma más rápida de comenzar con Laravel, Vue y Vite.
React
Si deseas construir tu frontend usando el framework React, entonces también necesitarás instalar el plugin @vitejs/plugin-react:
npm install --save-dev @vitejs/plugin-react
Luego puedes incluir el plugin en tu archivo de configuración 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(),
],
});
Necesitarás asegurarte de que cualquier archivo que contenga JSX tenga una extensión .jsx o .tsx, recordando actualizar tu punto de entrada, si es necesario, como se muestra arriba.
También necesitarás incluir la directiva adicional @viteReactRefresh junto con tu directiva @vite existente.
@viteReactRefresh
@vite('resources/js/app.jsx')
La directiva @viteReactRefresh debe llamarse antes de la directiva @vite.
Los kits de inicio de Laravel ya incluyen la configuración adecuada de Laravel, React y Vite. Consulta Laravel Breeze para la forma más rápida de comenzar con Laravel, React y Vite.
Inertia
El plugin de Laravel Vite proporciona una función conveniente resolvePageComponent para ayudarte a resolver tus componentes de página de Inertia. A continuación se muestra un ejemplo del uso del helper con Vue 3; sin embargo, también puedes utilizar la función en otros frameworks como 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 }) {
return createApp({ render: () => h(App, props) })
.use(plugin)
.mount(el)
},
});
Si estás usando la función de división de código de Vite con Inertia, te recomendamos configurar la precarga de activos.
Los kits de inicio de Laravel ya incluyen la configuración adecuada de Laravel, Inertia y Vite. Consulta Laravel Breeze para la forma más rápida de comenzar con Laravel, Inertia y Vite.
Procesamiento de URLs
Al usar Vite y referenciar activos en el HTML, CSS o JS de tu aplicación, hay un par de advertencias a considerar. Primero, si referencias activos con una ruta absoluta, Vite no incluirá el activo en la construcción; por lo tanto, debes asegurarte de que el activo esté disponible en tu directorio público. Debes evitar usar rutas absolutas cuando uses un punto de entrada CSS dedicado porque, durante el desarrollo, los navegadores intentarán cargar estas rutas desde el servidor de desarrollo de Vite, donde se aloja el CSS, en lugar de desde tu directorio público.
Al referenciar rutas de activos relativas, debes recordar que las rutas son relativas al archivo donde se referencian. Cualquier activo referenciado a través de una ruta relativa será reescrito, versionado y agrupado por Vite.
Considera la siguiente estructura de proyecto:
public/
taylor.png
resources/
js/
Pages/
Welcome.vue
images/
abigail.png
El siguiente ejemplo demuestra cómo Vite tratará las URLs relativas y absolutas:
<!-- Este activo no es manejado por Vite y no será incluido en la construcción -->
<img src="/taylor.png">
<!-- Este activo será reescrito, versionado y agrupado por Vite -->
<img src="../../images/abigail.png">
Trabajando con Hojas de Estilo
Puedes aprender más sobre el soporte de CSS de Vite dentro de la documentación de Vite. Si estás usando plugins de PostCSS como Tailwind, puedes crear un archivo postcss.config.js en la raíz de tu proyecto y Vite lo aplicará automáticamente:
export default {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
};
Los kits de inicio de Laravel ya incluyen la configuración adecuada de Tailwind, PostCSS y Vite. O, si deseas usar Tailwind y Laravel sin usar uno de nuestros kits de inicio, consulta la guía de instalación de Tailwind para Laravel.
Trabajando con Blade y Rutas
Procesamiento de Activos Estáticos con Vite
Al referenciar activos en tu JavaScript o CSS, Vite los procesa y versiona automáticamente. Además, al construir aplicaciones basadas en Blade, Vite también puede procesar y versionar activos estáticos que solo referencies en plantillas Blade.
Sin embargo, para lograr esto, necesitas hacer que Vite sea consciente de tus activos importando los activos estáticos en el punto de entrada de la aplicación. Por ejemplo, si deseas procesar y versionar todas las imágenes almacenadas en resources/images y todas las fuentes almacenadas en resources/fonts, debes agregar lo siguiente en el punto de entrada resources/js/app.js de tu aplicación:
import.meta.glob([
'../images/**',
'../fonts/**',
]);
Estos activos ahora serán procesados por Vite al ejecutar npm run build. Luego puedes referenciar estos activos en plantillas Blade usando el método Vite::asset, que devolverá la URL versionada para un activo dado:
<img src="{{ Vite::asset('resources/images/logo.png') }}">
Actualización Automática al Guardar
Cuando tu aplicación se construye usando renderizado del lado del servidor tradicional con Blade, Vite puede mejorar tu flujo de trabajo de desarrollo actualizando automáticamente el navegador cuando realizas cambios en los archivos de vista de tu aplicación. Para comenzar, simplemente puedes especificar la opción refresh como true.
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
// ...
refresh: true,
}),
],
});
Cuando la opción refresh es true, guardar archivos en los siguientes directorios hará que el navegador realice una actualización de página completa mientras ejecutas npm run dev:
app/Livewire/**app/View/Components/**lang/**resources/lang/**resources/views/**routes/**
Observar el directorio routes/** es útil si estás utilizando Ziggy para generar enlaces de ruta dentro del frontend de tu aplicación.
Si estas rutas predeterminadas no se ajustan a tus necesidades, puedes especificar tu propia lista de rutas a observar:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
// ...
refresh: ['resources/views/**'],
}),
],
});
En el fondo, el plugin de Laravel Vite utiliza el paquete vite-plugin-full-reload, que ofrece algunas opciones de configuración avanzada para ajustar el comportamiento de esta función. Si necesitas este nivel de personalización, puedes proporcionar una definición de configuración:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
// ...
refresh: [{
paths: ['path/to/watch/**'],
config: { delay: 300 }
}],
}),
],
});
Aliases
Es común en las aplicaciones JavaScript crear aliases para directorios referenciados regularmente. Pero, también puedes crear aliases para usar en Blade usando el método macro en la clase Illuminate\Support\Facades\Vite. Típicamente, las «macros» deben definirse dentro del método boot de un proveedor de servicios:
/**
* Inicializar cualquier servicio de la aplicación.
*/
public function boot(): void
{
Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
}
Una vez que se ha definido una macro, se puede invocar dentro de tus plantillas. Por ejemplo, podemos usar la macro image definida arriba para referenciar un activo ubicado en resources/images/logo.png:
<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">
Prefetching de Activos
Al construir una SPA usando la función de división de código de Vite, los activos requeridos se obtienen en cada navegación de página. Este comportamiento puede llevar a un retraso en la renderización de la UI. Si esto es un problema para tu framework frontend de elección, Laravel ofrece la capacidad de prefetching de los activos JavaScript y CSS de tu aplicación en la carga inicial de la página.
Puedes instruir a Laravel para que haga prefetching de tus activos invocando el método Vite::prefetch en el método boot de un proveedor de servicios:
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Vite;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Registrar cualquier servicio de la aplicación.
*/
public function register(): void
{
// ...
}
/**
* Inicializar cualquier servicio de la aplicación.
*/
public function boot(): void
{
Vite::prefetch(concurrency: 3);
}
}
En el ejemplo anterior, los activos se prefetcharán con un máximo de 3 descargas concurrentes en cada carga de página. Puedes modificar la concurrencia para adaptarla a las necesidades de tu aplicación o especificar que no haya límite de concurrencia si la aplicación debe descargar todos los activos a la vez:
/**
* Inicializar cualquier servicio de la aplicación.
*/
public function boot(): void
{
Vite::prefetch();
}
Por defecto, el prefetching comenzará cuando se dispare el evento de carga de la página. Si deseas personalizar cuándo comienza el prefetching, puedes especificar un evento que Vite escuchará:
/**
* Inicializar cualquier servicio de la aplicación.
*/
public function boot(): void
{
Vite::prefetch(event: 'vite:prefetch');
}
Dado el código anterior, el prefetching comenzará cuando despaches manualmente el evento vite:prefetch en el objeto window. Por ejemplo, podrías hacer que el prefetching comience tres segundos después de que la página se cargue:
<script>
addEventListener('load', () => setTimeout(() => {
dispatchEvent(new Event('vite:prefetch'))
}, 3000))
</script>
URLs Base Personalizadas
Si los activos compilados por Vite se despliegan en un dominio separado de tu aplicación, como a través de un CDN, debes especificar la variable de entorno ASSET_URL dentro del archivo .env de tu aplicación:
ASSET_URL=https://cdn.example.com
Después de configurar la URL del activo, todas las URLs reescritas a tus activos se prefijarán con el valor configurado:
https://cdn.example.com/build/assets/app.9dce8d17.js
Recuerda que las URLs absolutas no se reescriben por Vite, por lo que no se prefijarán.
Variables de Entorno
Puedes inyectar variables de entorno en tu JavaScript prefijándolas con VITE_ en el archivo .env de tu aplicación:
VITE_SENTRY_DSN_PUBLIC=http://example.com
Puedes acceder a las variables de entorno inyectadas a través del objeto import.meta.env:
import.meta.env.VITE_SENTRY_DSN_PUBLIC
Deshabilitando Vite en Pruebas
La integración de Vite en Laravel intentará resolver tus activos mientras ejecutas tus pruebas, lo que requiere que ejecutes el servidor de desarrollo de Vite o construyas tus activos.
Si prefieres simular Vite durante las pruebas, puedes llamar al método withoutVite, que está disponible para cualquier prueba que extienda la clase TestCase de Laravel:
test('without vite example', function () {
$this->withoutVite();
// ...
});
Si deseas deshabilitar Vite para todas las pruebas, puedes llamar al método withoutVite desde el método setUp en tu clase base TestCase:
<?php
namespace Tests;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
abstract class TestCase extends BaseTestCase
{
protected function setUp(): void
{
parent::setUp();
$this->withoutVite();
}
}
Renderizado del Lado del Servidor (SSR)
El plugin de Laravel Vite facilita la configuración del renderizado del lado del servidor con Vite. Para comenzar, crea un punto de entrada SSR en resources/js/ssr.js y especifica el punto de entrada pasando una opción de configuración al plugin de 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',
}),
],
});
Para asegurarte de no olvidar reconstruir el punto de entrada SSR, te recomendamos aumentar el script build en el package.json de tu aplicación para crear tu construcción SSR:
"scripts": {
"dev": "vite",
"build": "vite build && vite build --ssr"
}
Luego, para construir y arrancar el servidor SSR, puedes ejecutar los siguientes comandos:
npm run build
node bootstrap/ssr/ssr.js
Si estás usando SSR con Inertia, puedes usar el comando Artisan inertia:start-ssr para iniciar el servidor SSR:
php artisan inertia:start-ssr
Los kits de inicio de Laravel ya incluyen la configuración adecuada de Laravel, Inertia SSR y Vite. Consulta Laravel Breeze para la forma más rápida de comenzar con Laravel, Inertia SSR y Vite.
Atributos de Etiquetas de Script y Estilo
Nonce de Política de Seguridad de Contenidos (CSP)
Si deseas incluir un atributo nonce en tus etiquetas de script y estilo como parte de tu Política de Seguridad de Contenidos, puedes generar o especificar un nonce usando el método useCspNonce dentro de un middleware personalizado:
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Symfony\Component\HttpFoundation\Response;
class AddContentSecurityPolicyHeaders
{
/**
* Manejar una solicitud entrante.
*
* @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()."'",
]);
}
}
Después de invocar el método useCspNonce, Laravel incluirá automáticamente los atributos nonce en todas las etiquetas de script y estilo generadas.
Si necesitas especificar el nonce en otro lugar, incluidas las directivas @route de Ziggy incluidas con los kits de inicio de Laravel, puedes recuperarlo usando el método cspNonce:
@routes(nonce: Vite::cspNonce())
Si ya tienes un nonce que deseas que Laravel use, puedes pasarlo al método useCspNonce:
Vite::useCspNonce($nonce);
Integridad de Subrecursos (SRI)
Si tu manifiesto de Vite incluye hashes de integridad para tus activos, Laravel agregará automáticamente el atributo integrity en cualquier etiqueta de script y estilo que genere para hacer cumplir la Integridad de Subrecursos. Por defecto, Vite no incluye el hash de integridad en su manifiesto, pero puedes habilitarlo instalando el plugin vite-plugin-manifest-sri de NPM:
npm install --save-dev vite-plugin-manifest-sri
Luego puedes habilitar este plugin en tu archivo de configuración 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(),
],
});
Si es necesario, también puedes personalizar la clave del manifiesto donde se puede encontrar el hash de integridad:
use Illuminate\Support\Facades\Vite;
Vite::useIntegrityKey('custom-integrity-key');
Si deseas deshabilitar esta detección automática por completo, puedes pasar false al método useIntegrityKey:
Vite::useIntegrityKey(false);
Atributos Arbitrarios
Si necesitas incluir atributos adicionales en tus etiquetas de script y estilo, como el atributo data-turbo-track, puedes especificarlos a través de los métodos useScriptTagAttributes y useStyleTagAttributes. Típicamente, estos métodos deben invocarse desde un proveedor de servicios:
use Illuminate\Support\Facades\Vite;
Vite::useScriptTagAttributes([
'data-turbo-track' => 'reload', // Especificar un valor para el atributo...
'async' => true, // Especificar un atributo sin un valor...
'integrity' => false, // Excluir un atributo que de otro modo se incluiría...
]);
Vite::useStyleTagAttributes([
'data-turbo-track' => 'reload',
]);
Si necesitas agregar atributos condicionalmente, puedes pasar un callback que recibirá la ruta de origen del activo, su URL, su chunk de manifiesto y el manifiesto completo:
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,
]);
Los argumentos $chunk y $manifest serán null mientras el servidor de desarrollo de Vite esté en ejecución.
Personalización Avanzada
De fábrica, el plugin de Vite de Laravel utiliza convenciones sensatas que deberían funcionar para la mayoría de las aplicaciones; sin embargo, a veces puede que necesites personalizar el comportamiento de Vite. Para habilitar opciones de personalización adicionales, ofrecemos los siguientes métodos y opciones que pueden usarse en lugar de la directiva Blade @vite:
<!doctype html>
<head>
{{-- ... --}}
{{
Vite::useHotFile(storage_path('vite.hot')) // Personalizar el archivo "hot"...
->useBuildDirectory('bundle') // Personalizar el directorio de construcción...
->useManifestFilename('assets.json') // Personalizar el nombre del archivo de manifiesto...
->withEntryPoints(['resources/js/app.js']) // Especificar los puntos de entrada...
->createAssetPathsUsing(function (string $path, ?bool $secure) { // Personalizar la generación de rutas de activos en el backend...
return "https://cdn.example.com/{$path}";
})
}}
</head>
Dentro del archivo vite.config.js, debes especificar la misma configuración:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
hotFile: 'storage/vite.hot', // Personalizar el archivo "hot"...
buildDirectory: 'bundle', // Personalizar el directorio de construcción...
input: ['resources/js/app.js'], // Especificar los puntos de entrada...
}),
],
build: {
manifest: 'assets.json', // Personalizar el nombre del archivo de manifiesto...
},
});
Corregir URLs del Servidor de Desarrollo
Algunos plugins dentro del ecosistema de Vite asumen que las URLs que comienzan con una barra inclinada siempre apuntarán al servidor de desarrollo de Vite. Sin embargo, debido a la naturaleza de la integración de Laravel, este no es el caso.
Por ejemplo, el plugin vite-imagetools genera URLs como la siguiente mientras Vite está sirviendo tus activos:
<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
El plugin vite-imagetools espera que la URL de salida sea interceptada por Vite y el plugin pueda manejar todas las URLs que comienzan con /@imagetools. Si estás usando plugins que esperan este comportamiento, necesitarás corregir manualmente las URLs. Puedes hacer esto en tu archivo vite.config.js usando la opción transformOnServe.
En este ejemplo particular, vamos a anteponer la URL del servidor de desarrollo a todas las ocurrencias de /@imagetools dentro del código generado:
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(),
],
});
Ahora, mientras Vite está sirviendo activos, generará URLs que apuntan al servidor de desarrollo de Vite:
- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
Mi cuenta de Google