Introducing Laravel 5 Elixir

  • November 11, 2014

Welcome to the incredibly popular Easy Laravel 5 companion blog. To celebrate the new edition's release (updated for Laravel 5.5!) use the discount code easteregg to receive 20% off the book or book/video package! » Buy the book

Last Updated: February 2, 2015

Writing code is but one of many tasks the modern developer has to juggle when working on even a simple web application. You'll want to compress images, minify CSS and JavaScript files, remove debugging statements, run unit tests, and perform countless other mundane duties. Keeping track of these responsibilities let alone ensuring you remember to carry them all out is a pretty tall order, particularly because you're presumably devoting the majority of your attention to creating and maintaining great application features.

The Laravel 5 developers hope to reduce some of the time and hassle associated with these sort of tasks by providing a new API called Laravel Elixir. The Elixir API integrates with Gulp, providing an easy solution for compiling your Laravel project's Less, Sass and CoffeeScript, and perform any other such administrative task. In this section I'll show you how to create and execute several Elixir tasks in conjunction with your Laravel application. But first because many readers are likely not familiar with Gulp I'd like to offer a quick introduction, including instructions for installing Gulp and it's dependencies.

Introducing Gulp

Gulp is a powerful open source build system you can use to automate all of the aforementioned tasks and many more. You'll automate away these headaches by writing Gulp tasks, and can save a great deal of time when doing so by integrating one or more of the hundreds of available Gulp plugins. In this section I'll show you how to install and configure Gulp for subsequent use within Elixir.

Installing Gulp

Because Gulp is built atop Node.js, you'll first need to install Node. No matter your operating system this is easily done by downloading one of the installers via the Node.js website. If you'd prefer to build Node from source you can download the source code via this link. If like me you're a Mac user, you can install Node via Homebrew. Linux users additionally likely have access to Node via their distribution's package manager.

Once installed you can confirm Node is accessible via the command-line by retrieving the Node version number:

$ node -v
v0.10.36

Node users have access to a great number of third-party libraries known as Node Packaged Modules (NPM). You can install these modules via the aptly-named npm utility. We'll use npm to install Gulp:

$ npm install -g gulp

Once installed you should be able to execute Gulp from the command-line:

$ gulp -v
[14:12:51] CLI version 3.8.10

With Gulp installed it's time to install Elixir!

Installing Elixir

Laravel 5 applications automatically include a file named package.json which resides in the project's root directory. This file looks like this:

{
  "devDependencies": {
    "gulp": "^3.8.8",
    "laravel-elixir": "*"
  }
}

Node's npm package manager uses package.json to learn about and install a project's Node module dependencies. As you can see, a default Laravel project requires two Node packages: gulp and laravel-elixir. You can install these packages locally using the package manager like so:

$ npm install

Once complete, you'll find a new directory named node_modules has been created within your project's root directory, and within in it you'll find the gulp and laravel-elixir packages.

Creating Your First Elixir Task

Your Laravel project includes a default gulpfile.js which defines your Elixir-flavored Gulp tasks. Inside this file you'll find an example Gulp task:

elixir(function(mix) {
    mix.less('app.less');
});

The mix.less task compiles a Less file, in this case the file named app.less. This file resides in resources/assets/less, and looks like this:

@import  "bootstrap/bootstrap";

@btn-font-weight: 300;
@font-family-sans-serif: "Roboto", Helvetica, Arial, sans-serif;

body, label, .checkbox label {
  font-weight: 300;
}

You're free to add other tasks to this function, meaning you can easily carry out multiple annoying and repetitive tasks in just a few keystrokes. You can execute these tasks by running gulp from within your project root directory:

$ gulp
[13:16:18] Using gulpfile ~/Software/dev.todoparrot.com/gulpfile.js
[13:16:18] Starting 'default'...
[13:16:18] Starting 'less'...
[13:16:19] Finished 'default' after 480 ms
[13:16:20] gulp-notify: [Laravel Elixir]
[13:16:20] Finished 'less' after 1.52 s

By executing gulp we've compiled app.less, saving the output to a file named app.css which resides in your project's public/css directory. Of course, in order to actually use the styles defined in the app.css file you'll need to reference it within your layout:

<link rel="stylesheet" href="/css/app.css">

Keep in mind that Elixir does not minify compiled CSS by default. You can however minify it by passing the --production option to gulp:

$ gulp --production

Compiling Your JavaScript Assets

You'll likely also want to manage your JavaScript assets. For instance if you use CoffeeScript, you'll place your CoffeeScript files in resources/assets/coffee (you'll need to create this directory). Here's a simple CoffeeScript statement which will display one of those annoying alert boxes in the browser:

alert "Hi I am annoying"

Save this statement to resources/assets/coffee/test.coffee. Next, modify your gulpfile.js file to look like this:

elixir(function(mix) {
    mix.less('app.less');
    mix.coffee();
});

Incidentally, you could also chain the commands together like so:

elixir(function(mix) {
    mix.less('app.less').coffee();
});

Save the changes and run gulp again:

$ gulp
[14:40:25] Using gulpfile ~/Software/dev.todoparrot.com/gulpfile.js
[14:40:25] Starting 'default'...
[14:40:25] Starting 'less'...
[14:40:26] Finished 'default' after 478 ms
[14:40:27] gulp-notify: [Laravel Elixir]
[14:40:27] Finished 'less' after 1.88 s
[14:40:27] Starting 'coffee'...
[14:40:27] gulp-notify: [Laravel Elixir]
[14:40:27] Finished 'coffee' after 236 ms

You'll see that a directory named js has been created inside public. Inside this directory you'll find the file test.js which contains the following JavaScript code:

(function() {
  alert("Hello world");
}).call(this);

Watching for Changes

Because you'll presumably be making regular tweaks to your CSS and JavaScript and will want to see the results in your development browser, consider using Elixir's watch command to automatically execute gulpfile.js anytime your assets change:

$ gulp watch

Other Elixir Tasks

Less and CoffeeScript compilation are but two of several Elixir features you can begin taking advantage of right now. Be sure to check out the Elixir README for an extended list of capabilities.

While Elixir is still very much a work in progress and documentation remains slim, this tool already holds bunches of potential. Stay tuned as I'll be sure to expand this section significantly in future revisions to include additional examples.