• Introducción
  • Instalación y configuración
  • Mezcla de ejecución
  • Trabajar con hojas de estilo
    • Menos
    • Hablar con descaro a
    • Aguja
    • PostCSS
    • CSS simple
    • Procesamiento de URL
    • Mapas de origen
  • Trabajando con JavaScript
    • Extracción de proveedores
    • Reaccionar
    • Vanilla JS
    • Configuración de paquete web personalizado
  • Copiar archivos y directorios
  • Control de versiones / Cache Busting
  • Recarga de Browsersync
  • Variables de entorno
  • Notificaciones

Introducción

Mezcla de Laravel proporciona una API fluida para definir los pasos de compilación de Webpack para su aplicación Laravel utilizando varios preprocesadores comunes de CSS y JavaScript. A través del encadenamiento de métodos simple, puede definir con fluidez su canalización de activos. Por ejemplo:

mix.js('resources/js/app.js','public/js').sass('resources/sass/app.scss','public/css');

Si alguna vez ha estado confundido y abrumado por comenzar con Webpack y la compilación de activos, le encantará Laravel Mix. Sin embargo, no es necesario que lo utilice mientras desarrolla su aplicación; puede utilizar cualquier herramienta de canalización de activos que desee, o incluso ninguna.

Instalación y configuración

Instalando Node

Antes de activar Mix, primero debe asegurarse de que Node.js y NPM estén instalados en su máquina.

node -v
npm -v

De forma predeterminada, Laravel Homestead incluye todo lo que necesita; sin embargo, si no está utilizando Vagrant, puede instalar fácilmente la última versión de Node y NPM utilizando simples instaladores gráficos de su página de descarga.

Mezcla de Laravel

El único paso restante es instalar Laravel Mix. Dentro de una nueva instalación de Laravel, encontrará una package.json archivo en la raíz de la estructura de su directorio. El valor por defecto package.json El archivo incluye todo lo que necesita para comenzar. Piensa en esto como tu composer.json archivo, excepto que define dependencias de nodo en lugar de PHP. Puede instalar las dependencias a las que hace referencia ejecutando:

npm install

Mezcla de ejecución

Mix es una capa de configuración sobre Webpack, por lo que para ejecutar sus tareas de Mix solo necesita ejecutar uno de los scripts de NPM que se incluyen con el Laravel predeterminado package.json expediente:

// Run all Mix tasks...
npm run dev

// Run all Mix tasks and minify output...
npm run production

Observando los activos en busca de cambios

los npm run watch El comando continuará ejecutándose en su terminal y observará todos los archivos relevantes para ver si hay cambios. Webpack luego recompilará automáticamente sus activos cuando detecte un cambio:

npm run watch

Puede encontrar que en ciertos entornos Webpack no se actualiza cuando cambian sus archivos. Si este es el caso en su sistema, considere usar el watch-poll mando:

npm run watch-poll

Trabajar con hojas de estilo

los webpack.mix.js file es su punto de entrada para toda la compilación de activos. Piense en ello como un envoltorio de configuración ligero alrededor de Webpack. Las tareas mixtas se pueden encadenar para definir exactamente cómo se deben compilar sus activos.

Menos

los less El método se puede utilizar para compilar Menos en CSS. Compilemos nuestro primario app.less archivo a public/css/app.css.

mix.less('resources/less/app.less','public/css');

Varias llamadas al less El método se puede utilizar para compilar varios archivos:

mix.less('resources/less/app.less','public/css').less('resources/less/admin.less','public/css');

Si desea personalizar el nombre de archivo del CSS compilado, puede pasar una ruta de archivo completa como segundo argumento al less método:

mix.less('resources/less/app.less','public/stylesheets/styles.css');

Si necesita anular el Opciones de complemento menos subyacentes, puede pasar un objeto como tercer argumento a mix.less():

mix.less('resources/less/app.less','public/css',
    strictMath:true);

Hablar con descaro a

los sass El método te permite compilar Hablar con descaro a en CSS. Puedes usar el método así:

mix.sass('resources/sass/app.scss','public/css');

De nuevo, como el less método, puede compilar varios archivos Sass en sus propios archivos CSS respectivos e incluso personalizar el directorio de salida del CSS resultante:

mix.sass('resources/sass/app.sass','public/css').sass('resources/sass/admin.sass','public/css/admin');

Adicional Opciones de complemento de Node-Sass puede proporcionarse como tercer argumento:

mix.sass('resources/sass/app.sass','public/css',
    precision:5);

Aguja

Similar a Less y Sass, el stylus El método te permite compilar Aguja en CSS:

mix.stylus('resources/stylus/app.styl','public/css');

También puede instalar complementos adicionales de Stylus, como Ruptura. Primero, instale el complemento en cuestión a través de NPM (npm install rupture) y luego solicítelo en su llamada a mix.stylus():

mix.stylus('resources/stylus/app.styl','public/css',use:[require('rupture')()]);

PostCSS

PostCSS, una poderosa herramienta para transformar su CSS, se incluye con Laravel Mix lista para usar. De forma predeterminada, Mix aprovecha el popular Autoprefixer plug-in para aplicar automáticamente todos los prefijos de proveedores CSS3 necesarios. Sin embargo, puede agregar cualquier complemento adicional que sea apropiado para su aplicación. Primero, instale el complemento deseado a través de NPM y luego haga referencia a él en su webpack.mix.js expediente:

mix.sass('resources/sass/app.scss','public/css').options(
        postCss:[require('postcss-css-variables')()]);

CSS simple

Si solo desea concatenar algunas hojas de estilo CSS simples en un solo archivo, puede usar el styles método.

mix.styles(['public/css/vendor/normalize.css','public/css/vendor/videojs.css'],'public/css/all.css');

Procesamiento de URL

Debido a que Laravel Mix se basa en Webpack, es importante comprender algunos conceptos de Webpack. Para la compilación de CSS, Webpack reescribirá y optimizará cualquier url() llamadas dentro de sus hojas de estilo. Si bien esto inicialmente puede sonar extraño, es una funcionalidad increíblemente poderosa. Imagina que queremos compilar Sass que incluye una URL relativa a una imagen:

.example 
    background:url('../images/example.png');

Caminos absolutos para cualquier url() se excluirá de la reescritura de URL. Por ejemplo, url('/images/thing.png') o url('http://example.com/images/thing.png') no se modificará.

De forma predeterminada, Laravel Mix y Webpack encontrarán example.png, cópialo en tu public/images carpeta, y luego reescriba el url() dentro de su hoja de estilo generada. Como tal, su CSS compilado será:

.example 
    background:url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);

Por muy útil que sea esta función, es posible que su estructura de carpetas existente ya esté configurada de la manera que desee. Si este es el caso, puede desactivar url() reescribiendo así:

mix.sass('resources/sass/app.scss','public/css').options(
        processCssUrls:false);

Con esta adición a tu webpack.mix.js archivo, Mix ya no coincidirá con ningún url() o copiar activos a su directorio público. En otras palabras, el CSS compilado se verá exactamente como lo escribió originalmente:

.example 
    background:url("../images/thing.png");

Mapas de origen

Aunque deshabilitados de forma predeterminada, los mapas de origen se pueden activar llamando al mix.sourceMaps() método en tu webpack.mix.js expediente. Aunque viene con un costo de compilación / rendimiento, esto proporcionará información de depuración adicional a las herramientas de desarrollo de su navegador cuando utilice activos compilados.

mix.js('resources/js/app.js','public/js').sourceMaps();

Estilo de mapeo de fuentes

Webpack ofrece una variedad de estilos de mapeo de origen. De forma predeterminada, el estilo de mapeo de origen de Mix se establece en eval-source-map, que proporciona un tiempo de reconstrucción rápido. Si desea cambiar el estilo de mapeo, puede hacerlo usando el sourceMaps método:

let productionSourceMaps =false;

mix.js('resources/js/app.js','public/js').sourceMaps(productionSourceMaps,'source-map');

Trabajando con JavaScript

Mix proporciona varias funciones para ayudarlo a trabajar con sus archivos JavaScript, como compilar ECMAScript 2015, empaquetar módulos, minificar y concatenar archivos JavaScript sin formato. Aún mejor, todo esto funciona a la perfección, sin requerir una onza de configuración personalizada:

mix.js('resources/js/app.js','public/js');

Con esta única línea de código, ahora puede aprovechar:

  • Sintaxis de ES2015.
  • Módulos
  • Compilación de .vue archivos.
  • Minificación para entornos de producción.

Extracción de proveedores

Una posible desventaja de agrupar todo el JavaScript específico de la aplicación con las bibliotecas de su proveedor es que dificulta el almacenamiento en caché a largo plazo. Por ejemplo, una sola actualización del código de su aplicación obligará al navegador a volver a descargar todas las bibliotecas de su proveedor, incluso si no han cambiado.

Si tiene la intención de realizar actualizaciones frecuentes en el JavaScript de su aplicación, debería considerar la posibilidad de extraer todas las bibliotecas de su proveedor en su propio archivo. De esta forma, un cambio en el código de su aplicación no afectará el almacenamiento en caché de su gran vendor.js expediente. Mix’s extract El método hace que esto sea muy sencillo:

mix.js('resources/js/app.js','public/js').extract(['vue'])

los extract El método acepta una matriz de todas las bibliotecas o módulos que desea extraer en un vendor.js expediente. Usando el fragmento anterior como ejemplo, Mix generará los siguientes archivos:

  • public/js/manifest.js: El tiempo de ejecución del manifiesto de Webpack
  • public/js/vendor.js: Las bibliotecas de su proveedor
  • public/js/app.js: Tu código de aplicación

Para evitar errores de JavaScript, asegúrese de cargar estos archivos en el orden correcto:

<script src="/js/manifest.js"></script><script src="/js/vendor.js"></script><script src="/js/app.js"></script>

Reaccionar

Mix puede instalar automáticamente los complementos de Babel necesarios para el soporte de React. Para comenzar, reemplace su mix.js() llamar con mix.react():

mix.react('resources/js/app.jsx','public/js');

Detrás de escena, Mix descargará e incluirá el babel-preset-react Complemento de Babel.

Vanilla JS

Similar a combinar hojas de estilo con mix.styles(), también puede combinar y minimizar cualquier número de archivos JavaScript con el scripts() método:

mix.scripts(['public/js/admin.js','public/js/dashboard.js'],'public/js/all.js');

Esta opción es particularmente útil para proyectos heredados en los que no necesita la compilación de Webpack para su JavaScript.

Una ligera variación de mix.scripts() es mix.babel(). Su firma de método es idéntica a scripts; sin embargo, el archivo concatenado recibirá la compilación de Babel, que traduce cualquier código ES2015 a JavaScript vanilla que todos los navegadores entenderán.

Configuración de paquete web personalizado

Detrás de escena, Laravel Mix hace referencia a un preconfigurado webpack.config.js file para que pueda comenzar a trabajar lo más rápido posible. Ocasionalmente, es posible que deba modificar manualmente este archivo. Es posible que tenga un cargador o complemento especial al que deba hacer referencia, o tal vez prefiera usar Stylus en lugar de Sass. En tales casos, tiene dos opciones:

Fusionar configuración personalizada

Mix proporciona un útil webpackConfig método que le permite fusionar cualquier modificación breve de configuración de Webpack. Esta es una opción particularmente atractiva, ya que no requiere que copie y mantenga su propia copia del webpack.config.js expediente. los webpackConfig acepta un objeto, que debe contener cualquier Configuración específica de Webpack que desea aplicar.

mix.webpackConfig(
    resolve:
        modules:[
            path.resolve(__dirname,'vendor/laravel/spark/resources/assets/js')]);

Archivos de configuración personalizados

Si desea personalizar completamente la configuración de su Webpack, copie el node_modules/laravel-mix/setup/webpack.config.js archivo al directorio raíz de su proyecto. A continuación, apunte todos los --config referencias en tu package.json archivo al archivo de configuración recién copiado. Si elige adoptar este enfoque de personalización, cualquier actualización ascendente futura de Mix webpack.config.js debe combinarse manualmente en su archivo personalizado.

Copiar archivos y directorios

los copy El método puede usarse para copiar archivos y directorios a nuevas ubicaciones. Esto puede resultar útil cuando un activo particular dentro de su node_modules el directorio debe reubicarse en su public carpeta.

mix.copy('node_modules/foo/bar.css','public/css/bar.css');

Al copiar un directorio, el copy El método aplanará la estructura del directorio. Para mantener la estructura original del directorio, debe utilizar la copyDirectory método en su lugar:

mix.copyDirectory('resources/img','public/img');

Control de versiones / Cache Busting

Muchos desarrolladores agregan un sufijo a sus activos compilados con una marca de tiempo o un token único para obligar a los navegadores a cargar los activos nuevos en lugar de entregar copias obsoletas del código. Mix puede manejar esto por usted usando el version método.

los version El método agregará automáticamente un hash único a los nombres de archivo de todos los archivos compilados, lo que permitirá un almacenamiento de caché más conveniente:

mix.js('resources/js/app.js','public/js').version();

Después de generar el archivo versionado, no sabrá el nombre exacto del archivo. Por lo tanto, debe usar el método global de Laravel. mix funcionar dentro de sus vistas para cargar el activo con el hash apropiado. los mix La función determinará automáticamente el nombre actual del archivo hash:

<script src=" mix('/js/app.js') "></script>

Debido a que los archivos versionados generalmente no son necesarios en el desarrollo, puede indicarle al proceso de versionado que solo se ejecute durante npm run production:

mix.js('resources/js/app.js','public/js');if(mix.inProduction())
    mix.version();

URL base de mezcla personalizada

Si sus activos compilados de Mix se implementan en un CDN separado de su aplicación, deberá cambiar la URL base generada por el mix función. Puede hacerlo agregando un mix_url opción de configuración a su config/app.php archivo de configuración:

'mix_url'=>env('MIX_ASSET_URL',null)

Después de configurar la URL de la mezcla, mix La función prefijará la URL configurada al generar URL para activos:

https://cdn.example.com/js/app.js?id=1964becbdd96414518cd

Recarga de Browsersync

BrowserSync puede monitorear automáticamente sus archivos en busca de cambios e inyectar sus cambios en el navegador sin requerir una actualización manual. Puede habilitar el soporte llamando al mix.browserSync() método:

mix.browserSync('my-domain.test');// Or...// https://browsersync.io/docs/options
mix.browserSync(
    proxy:'my-domain.test');

Puede pasar una cadena (proxy) u objeto (configuración de BrowserSync) a este método. A continuación, inicie el servidor de desarrollo de Webpack usando el npm run watch mando. Ahora, cuando modifique un script o un archivo PHP, observe cómo el navegador actualiza instantáneamente la página para reflejar sus cambios.

Variables de entorno

Puede inyectar variables de entorno en Mix poniendo como prefijo una clave en su .env archivar con MIX_:

MIX_SENTRY_DSN_PUBLIC=http://example.com

Una vez definida la variable en su .env archivo, puede acceder a él a través del process.env objeto. Si el valor cambia mientras está ejecutando un watch tarea, deberá reiniciar la tarea:

process.env.MIX_SENTRY_DSN_PUBLIC

Notificaciones

Cuando esté disponible, Mix mostrará automáticamente las notificaciones del sistema operativo para cada paquete. Esto le dará una retroalimentación instantánea, sobre si la compilación fue exitosa o no. Sin embargo, puede haber casos en los que prefiera deshabilitar estas notificaciones. Un ejemplo de ello podría ser la activación de Mix en su servidor de producción. Las notificaciones pueden desactivarse a través del disableNotifications método.

mix.disableNotifications();