Introduction
Laravel Elixir provides a clean, fluent API for defining basic Gulp tasks for your Laravel application. Elixir supports several common CSS and JavaScript pre-processors, and even testing tools.
If you've ever been confused about how to get started with Gulp and asset compilation, you will love Laravel Elixir!
Installation & Setup
Installing Node
Before triggering Elixir, you must first ensure that Node.js is installed on your machine.
node -v
By default, Laravel Homestead includes everything you need; however, if you aren't using Vagrant, then you can easily install Node by visiting their download page. Don't worry, it's quick and easy!
Gulp
Next, you'll want to pull in Gulp as a global NPM package like so:
npm install --global gulp
Laravel Elixir
The only remaining step is to install Elixir! With a new install of Laravel, you'll find a package.json file in the root. 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
Usage
Now that you've installed Elixir, you'll be compiling and concatenating in no time! The gulpfile.js file in your project's root directory contains all of your Elixir tasks.
Compile Less
elixir(function(mix) {
mix.less("app.less");
});
In the example above, Elixir assumes that your Less files are stored in resources/assets/less.
Compile Multiple Less Files
elixir(function(mix) {
mix.less([
'app.less',
'something-else.less'
]);
});
Compile Sass
elixir(function(mix) {
mix.sass("app.scss");
});
This assumes that your Sass files are stored in resources/assets/sass.
By default, Elixir, underneath the hood, uses the LibSass library for compilation. In some instances, it might prove advantageous to instead leverage the Ruby version, which, though slower, is more feature rich. Assuming that you have both Ruby and the Sass gem installed (gem install sass), you may enable Ruby-mode, like so:
elixir(function(mix) {
mix.rubySass("app.sass");
});
Compile Without Source Maps
elixir.config.sourcemaps = false;
elixir(function(mix) {
mix.sass("app.scss");
});
Source maps are enabled out of the box. As such, for each file that is compiled, you'll find a companion *.css.map file in the same directory. This mapping allows you to, when debugging, trace your compiled stylesheet selectors back to your original Sass or Less partials! Should you need to disable this functionality, however, the code sample above will do the trick.
Compile CoffeeScript
elixir(function(mix) {
mix.coffee();
});
This assumes that your CoffeeScript files are stored in resources/assets/coffee.
Compile All Less and CoffeeScript
elixir(function(mix) {
mix.less()
.coffee();
});
Trigger PHPUnit Tests
elixir(function(mix) {
mix.phpUnit();
});
Trigger PHPSpec Tests
elixir(function(mix) {
mix.phpSpec();
});
Combine Stylesheets
elixir(function(mix) {
mix.styles([
"normalize.css",
"main.css"
]);
});
Paths passed to this method are relative to the resources/assets/css directory.
Combine Stylesheets and Save to a Custom Directory
elixir(function(mix) {
mix.styles([
"normalize.css",
"main.css"
], 'public/build/css/everything.css');
});
Combine Stylesheets From A Custom Base Directory
elixir(function(mix) {
mix.styles([
"normalize.css",
"main.css"
], 'public/build/css/everything.css', 'public/css');
});
The third argument to both the styles and scripts methods determines the relative directory for all paths passed to the methods.
Combine All Styles in a Directory
elixir(function(mix) {
mix.stylesIn("public/css");
});
Combine Scripts
elixir(function(mix) {
mix.scripts([
"jquery.js",
"app.js"
]);
});
Again, this assumes all paths are relative to the resources/assets/js directory.
Combine All Scripts in a Directory
elixir(function(mix) {
mix.scriptsIn("public/js/some/directory");
});
Combine Multiple Sets of Scripts
elixir(function(mix) {
mix.scripts(['jquery.js', 'main.js'], 'public/js/main.js')
.scripts(['forum.js', 'threads.js'], 'public/js/forum.js');
});
Version / Hash A File
elixir(function(mix) {
mix.version("css/all.css");
});
This will append a unique hash to the filename, allowing for cache-busting. For example, the generated file name will look something like: all-16d570a7.css.
Within your views, you may use the elixir() function to load the appropriately hashed asset. Here's an example:
<link rel="stylesheet" href="{{ elixir("css/all.css") }}">
Behind the scenes, the elixir() function will determine the name of the hashed file that should be included. Don't you feel the weight lifting off your shoulders already?
You may also pass an array to the version method to version multiple files:
elixir(function(mix) {
mix.version(["css/all.css", "js/app.js"]);
});
<link rel="stylesheet" href="{{ elixir("css/all.css") }}">
<script src="{{ elixir("js/app.js") }}"></script>
Copy a File to a New Location
elixir(function(mix) {
mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
});
Copy an Entire Directory to a New Location
elixir(function(mix) {
mix.copy('vendor/package/views', 'resources/views');
});
Trigger Browserify
elixir(function(mix) {
mix.browserify('index.js');
});
Want to require modules in the browser? Hoping to use EcmaScript 6 sooner than later? Need a built-in JSX transformer? If so, Browserify, along with the browserify Elixir task, will handle the job nicely.
This task assumes that your scripts are stored in resources/assets/js, though you're free to override the default.
Method Chaining
Of course, you may chain almost all of Elixir's methods together to build your recipe:
elixir(function(mix) {
mix.less("app.less")
.coffee()
.phpUnit()
.version("css/bootstrap.css");
});
Gulp
Now that you've told Elixir which tasks to execute, you only need to trigger Gulp from the command line.
Execute All Registered Tasks Once
gulp
Watch Assets For Changes
gulp watch
Only Compile Scripts
gulp scripts
Only Compile Styles
gulp styles
Watch Tests And PHP Classes for Changes
gulp tdd
Note: All tasks will assume a development environment, and will exclude minification. For production, use
gulp --production.
Custom Tasks and Extensions
Sometimes, you'll want to hook your own Gulp tasks into Elixir. Perhaps you have a special bit of functionality that you'd like Elixir to mix and watch for you. No problem!
As an example, imagine that you have a general task that simply speaks a bit of text when called.
gulp.task("speak", function() {
var message = "Tea...Earl Grey...Hot";
gulp.src("").pipe(shell("say " + message));
});
Easy enough. From the command line, you may, of course, call gulp speak to trigger the task. To add it to Elixir, however, use the mix.task() method:
elixir(function(mix) {
mix.task('speak');
});
That's it! Now, each time you run Gulp, your custom "speak" task will be executed alongside any other Elixir tasks that you've mixed in. To additionally register a watcher, so that your custom tasks will be re-triggered each time one or more files are modified, you may pass a regular expression as the second argument.
elixir(function(mix) {
mix.task('speak', 'app/**/*.php');
});
By adding this second argument, we've instructed Elixir to re-trigger the "speak" task each time a PHP file in the "app/" directory is saved.
For even more flexibility, you can create full Elixir extensions. Using the previous "speak" example, you may write an extension, like so:
var gulp = require("gulp");
var shell = require("gulp-shell");
var elixir = require("laravel-elixir");
elixir.extend("speak", function(message) {
gulp.task("speak", function() {
gulp.src("").pipe(shell("say " + message));
});
return this.queueTask("speak");
});
Notice that we extend Elixir's API by passing the name that we will reference within our Gulpfile, as well as a callback function that will create the Gulp task.
As before, if you want your custom task to be monitored, then register a watcher.
this.registerWatcher("speak", "app/**/*.php");
This lines designates that when any file that matches the regular expression, app/**/*.php, is modified, we want to trigger the speak task.
That's it! You may either place this at the top of your Gulpfile, or instead extract it to a custom tasks file. If you choose the latter approach, simply require it into your Gulpfile, like so:
require("./custom-tasks")
You're done! Now, you can mix it in.
elixir(function(mix) {
mix.speak("Tea, Earl Grey, Hot");
});
With this addition, each time you trigger Gulp, Picard will request some tea.