🎨 Laravel Mix y gestión de assets

🎨 Laravel Mix y gestión de assets

Compila, optimiza y organiza tus CSS y JavaScript con facilidad

Laravel Mix es una capa sobre webpack que simplifica la compilación y el manejo de assets (CSS, SASS, JS, imágenes). Con pocos comandos puedes transformar, concatenar, versionar y optimizar tus archivos para desarrollo y producción.

En esta entrada veremos la configuración básica, ejemplos reales (SASS → CSS, ES6 → ES5), versionado para cache-busting, y cómo integrar Mix con Laravel (y con Blade) paso a paso.

🔧 Requisitos previos

Tener Node.js (v12+) y npm o Yarn instalados.
Un proyecto Laravel ya creado (con package.json inicial).
Conocimientos básicos de NPM scripts y archivos frontend.

package.json (fragmento)

{
  "private": true,
  "scripts": {
    "dev": "npm run development",
    "development": "mix",
    "watch": "mix watch",
    "hot": "mix watch --hot",
    "prod": "npm run production",
    "production": "mix --production"
  },
  "devDependencies": {
    "laravel-mix": "^6.0.0",
    "sass": "^1.32.0",
    "sass-loader": "^10.1.1"
  }
}

⚙️ Archivo `webpack.mix.js`

En la raíz del proyecto encontrarás (o crearás) webpack.mix.js. Aquí defines las tareas que Laravel Mix ejecutará.

webpack.mix.js

const mix = require('laravel-mix');

/*
 |--------------------------------------------------------------------------
 | Mix Asset Management
 |--------------------------------------------------------------------------
 |
 | Mix simplifies Webpack configuration for common tasks like compiling
 | SASS, bundling JS, versioning, copying assets and more.
 |
 */

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

if (mix.inProduction()) {
  mix.version();
}

Este ejemplo compila resources/js/app.js a public/js/app.js y SASS a CSS. Además, en producción aplica versionado para cache-busting.

📁 Estructura típica de assets

resources/js/app.js → punto de entrada JS (imports, Vue/React, etc.)
resources/sass/app.scss → variables y estilos principales (SASS)
public/js/ y public/css/ → archivos compilados para servir
webpack.mix.js → configuración de Mix

resources/js/app.js (ejemplo)

// resources/js/app.js
import './bootstrap'; // file with axios, CSRF setup
import '../sass/app.scss';

console.log('App JS cargado');

// Ejemplo ES6
const saludo = (nombre = 'Alumno') => `¡Hola ${nombre}!`;
console.log(saludo('María'));

🎨 SASS: variables y uso

Ejemplo simple de resources/sass/app.scss con variables y mixins:

resources/sass/app.scss

// variables
$primary-color: #2b6cb0;
$radius: 6px;

body {
  font-family: Arial, sans-serif;
  background: #f8fafc;
  color: #1a202c;
}

.btn-custom {
  background: $primary-color;
  color: #fff;
  border-radius: $radius;
  padding: 0.5rem 1rem;
}

Al compilar, estos SASS se convertirán a CSS compatible con todos los navegadores (según tu configuración).

📦 Comandos comunes

npm install → instala dependencias.
npm run dev → compila para desarrollo (source maps).
npm run watch → recompila automáticamente al guardar archivos.
npm run prod → compila y optimiza para producción (minificación + version).

npm install
npm run dev
npm run watch
npm run prod

🔁 Versionado (Cache-busting)

En producción conviene versionar los assets para forzar al navegador a cargar la versión nueva. Mix ofrece mix.version() que genera nombres como app.css?id=abcd1234 o crea la carpeta mix-manifest.json.

En Blade

<!-- resources/views/layouts/app.blade.php -->
<link rel="stylesheet" href="{{ mix('css/app.css') }}">
<script src="{{ mix('js/app.js') }}" defer></script>

📂 Copiar activos estáticos

Mix también puede copiar carpetas completas (imágenes, fuentes) a public/:

mix.copyDirectory('resources/images', 'public/images');
mix.copyDirectory('resources/fonts', 'public/fonts');

🧪 Simulador visual: cómo se incluyen los assets

Selecciona si estás en desarrollo o producción y verás el enlace que deberías usar en Blade.

Entorno:

Nombre de asset (ej: css/app.css o js/app.js):

Aquí aparecerá el enlace generado.

🛠️ Problemas comunes y soluciones

No se ven los cambios: ejecuta npm run dev o npm run watch.
Error de compilación: revisa la versión de Node y dependencias, elimina node_modules y reinstala.
mix-manifest.json no coincide: limpia la caché del navegador o ejecuta npm run prod para regenear los archivos.
Problemas con SASS: asegura tener sass y sass-loader en devDependencies.

✅ Buenas prácticas

Usa npm run watch en desarrollo para recompilación automática.
Versiona assets en producción (mix.version()).
Separa lógica JS y CSS por componentes para mantener orden.
Usa mix.copyDirectory para mantener imágenes y fuentes accesibles.
Revisa mix.options({ processCssUrls: false }) si tienes problemas con rutas en CSS.

🏠 Volver al Índice ➡️ Siguiente tema: 🧰 Integrar Bootstrap con Laravel

🎨 Laravel Mix y gestión de assets