Compiling Assets (Mix)
Introduction
Laravel Mix provides a fluent API for defining Webpack build steps for your Laravel application using several common CSS and JavaScript pre-processors. Through simple method chaining, you can fluently define your asset pipeline. For example:
mix.js('resources/js/app.js', 'public/js')
.sass('resources/sass/app.scss', 'public/css');
If you've ever been confused and overwhelmed about getting started with Webpack and asset compilation, you will love Laravel Mix. However, you are not required to use it while developing your application; you are free to use any asset pipeline tool you wish, or even none at all.
Installation & Setup
Installing Node
Before triggering Mix, you must first ensure that Node.js and NPM are installed on your machine.
node -v
npm -v
By default, Laravel Homestead includes everything you need; however, if you aren't using Vagrant, then you can easily install the latest version of Node and NPM using simple graphical installers from their download page.
Laravel Mix
The only remaining step is to install Laravel Mix. Within a fresh installation of Laravel, you'll find a package.json
file in the root of your directory structure. The default package.json
file includes everything you need to get started. Think of this like your composer.json
file, except it defines Node dependencies instead of PHP. You may install the dependencies it references by running:
npm install
Running Mix
Mix is a configuration layer on top of Webpack, so to run your Mix tasks you only need to execute one of the NPM scripts that is included with the default Laravel package.json
file:
// Run all Mix tasks...
npm run dev
// Run all Mix tasks and minify output...
npm run production
Watching Assets For Changes
The npm run watch
command will continue running in your terminal and watch all relevant files for changes. Webpack will then automatically recompile your assets when it detects a change:
npm run watch
You may find that in certain environments Webpack isn't updating when your files change. If this is the case on your system, consider using the watch-poll
command:
npm run watch-poll
Working With Stylesheets
The webpack.mix.js
file is your entry point for all asset compilation. Think of it as a light configuration wrapper around Webpack. Mix tasks can be chained together to define exactly how your assets should be compiled.
Less
The less
method may be used to compile Less into CSS. Let's compile our primary app.less
file to public/css/app.css
.
mix.less('resources/less/app.less', 'public/css');
Multiple calls to the less
method may be used to compile multiple files:
mix.less('resources/less/app.less', 'public/css')
.less('resources/less/admin.less', 'public/css');
If you wish to customize the file name of the compiled CSS, you may pass a full file path as the second argument to the less
method:
mix.less('resources/less/app.less', 'public/stylesheets/styles.css');
If you need to override the underlying Less plug-in options, you may pass an object as the third argument to mix.less()
:
mix.less('resources/less/app.less', 'public/css', {
strictMath: true
});
Sass
The sass
method allows you to compile Sass into CSS. You may use the method like so:
mix.sass('resources/sass/app.scss', 'public/css');
Again, like the less
method, you may compile multiple Sass files into their own respective CSS files and even customize the output directory of the resulting CSS:
mix.sass('resources/sass/app.sass', 'public/css')
.sass('resources/sass/admin.sass', 'public/css/admin');
Additional Node-Sass plug-in options may be provided as the third argument:
mix.sass('resources/sass/app.sass', 'public/css', {
precision: 5
});
Stylus
Similar to Less and Sass, the stylus
method allows you to compile Stylus into CSS:
mix.stylus('resources/stylus/app.styl', 'public/css');
You may also install additional Stylus plug-ins, such as Rupture. First, install the plug-in in question through NPM (npm install rupture
) and then require it in your call to mix.stylus()
:
mix.stylus('resources/stylus/app.styl', 'public/css', {
use: [
require('rupture')()
]
});
PostCSS
PostCSS, a powerful tool for transforming your CSS, is included with Laravel Mix out of the box. By default, Mix leverages the popular Autoprefixer plug-in to automatically apply all necessary CSS3 vendor prefixes. However, you're free to add any additional plug-ins that are appropriate for your application. First, install the desired plug-in through NPM and then reference it in your webpack.mix.js
file:
mix.sass('resources/sass/app.scss', 'public/css')
.options({
postCss: [
require('postcss-css-variables')()
]
});
Plain CSS
If you would just like to concatenate some plain CSS stylesheets into a single file, you may use the styles
method.
mix.styles([
'public/css/vendor/normalize.css',
'public/css/vendor/videojs.css'
], 'public/css/all.css');
URL Processing
Because Laravel Mix is built on top of Webpack, it's important to understand a few Webpack concepts. For CSS compilation, Webpack will rewrite and optimize any url()
calls within your stylesheets. While this might initially sound strange, it's an incredibly powerful piece of functionality. Imagine that we want to compile Sass that includes a relative URL to an image:
.example {
background: url('../images/example.png');
}
Absolute paths for any given url()
will be excluded from URL-rewriting. For example, url('/images/thing.png')
or url('http://example.com/images/thing.png')
won't be modified.
By default, Laravel Mix and Webpack will find example.png
, copy it to your public/images
folder, and then rewrite the url()
within your generated stylesheet. As such, your compiled CSS will be:
.example {
background: url(/images/example.png?d41d8cd98f00b204e9800998ecf8427e);
}
As useful as this feature may be, it's possible that your existing folder structure is already configured in a way you like. If this is the case, you may disable url()
rewriting like so:
mix.sass('resources/app/app.scss', 'public/css')
.options({
processCssUrls: false
});
With this addition to your webpack.mix.js
file, Mix will no longer match any url()
or copy assets to your public directory. In other words, the compiled CSS will look just like how you originally typed it:
.example {
background: url("../images/thing.png");
}