elixir.md

Laravel Elixir

• Introduction
• Installation & Setup
• Running Elixir
• Working With Stylesheets
  • Less
  • Sass
  • Plain CSS
  • Source Maps
• Working With Scripts
  • CoffeeScript
  • Browserify
  • Babel
  • Scripts
• Copying Files & Directories
• Versioning / Cache Busting
• BrowserSync
• Calling Existing Gulp Tasks
• Writing Elixir Extensions

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. Using method chaining, Elixir allows you to fluently define your asset pipeline. For example:

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

If you've ever been confused about how to get started with Gulp and asset compilation, you will love Laravel Elixir. 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 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.

Gulp

Next, you'll want to pull in Gulp as a global NPM package:

npm install --global gulp-cli

If you use a version control system, you may wish to run the npm shrinkwrap to lock your NPM requirements:

 npm shrinkwrap

Once you have run this command, feel free to commit the npm-shrinkwrap.json into source control.

Laravel Elixir

The only remaining step is to install Elixir! Within a fresh installation 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

If you are developing on a Windows system or you are running your VM on a Windows host system, you may need to run the npm install command with the --no-bin-links switch enabled:

npm install --no-bin-links

Running Elixir

Elixir is built on top of Gulp, so to run your Elixir tasks you only need to run the gulp command in your terminal. Adding the --production flag to the command will instruct Elixir to minify your CSS and JavaScript files:

// Run all tasks...
gulp

// Run all tasks and minify all CSS and JavaScript...
gulp --production

Watching Assets For Changes

Since it is inconvenient to run the gulp command on your terminal after every change to your assets, you may use the gulp watch command. This command will continue running in your terminal and watch your assets for any changes. When changes occur, new files will automatically be compiled:

gulp watch

Working With Stylesheets

The gulpfile.js file in your project's root directory contains all of your Elixir tasks. Elixir tasks can be chained together to define exactly how your assets should be compiled.

Less

To compile Less into CSS, you may use the less method. The less method assumes that your Less files are stored in resources/assets/less. By default, the task will place the compiled CSS for this example in public/css/app.css:

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

You may also combine multiple Less files into a single CSS file. Again, the resulting CSS will be placed in public/css/app.css:

elixir(function(mix) {
    mix.less([
        'app.less',
        'controllers.less'
    ]);
});

If you wish to customize the output location of the compiled CSS, you may pass a second argument to the less method:

elixir(function(mix) {
    mix.less('app.less', 'public/stylesheets');
});

// Specifying a specific output filename...
elixir(function(mix) {
    mix.less('app.less', 'public/stylesheets/style.css');
});

Sass

The sass method allows you to compile Sass into CSS. Assuming your Sass files are stored at resources/assets/sass, you may use the method like so:

elixir(function(mix) {
    mix.sass('app.scss');
});

Again, like the less method, you may compile multiple Sass files into a single CSS file, and even customize the output directory of the resulting CSS:

elixir(function(mix) {
    mix.sass([
        'app.scss',
        'controllers.scss'
    ], 'public/assets/css');
});

Plain CSS

If you would just like to combine some plain CSS stylesheets into a single file, you may use the styles method. Paths passed to this method are relative to the resources/assets/css directory and the resulting CSS will be placed in public/css/all.css:

elixir(function(mix) {
    mix.styles([
        'normalize.css',
        'main.css'
    ]);
});

Of course, you may also output the resulting file to a custom location by passing a second argument to the styles method:

elixir(function(mix) {
    mix.styles([
        'normalize.css',
        'main.css'
    ], 'public/assets/css');
});

Source Maps

Source maps are enabled out of the box. So, for each file that is compiled you will find a companion *.css.map file in the same directory. This mapping allows you to trace your compiled stylesheet selectors back to your original Sass or Less while debugging in your browser.

If you do not want source maps generated for your CSS, you may disable them using a simple configuration option:

elixir.config.sourcemaps = false;

elixir(function(mix) {
    mix.sass('app.scss');
});

Working With Scripts

Elixir also provides several functions to help you work with your JavaScript files, such as compiling ECMAScript 6, compiling CoffeeScript, Browserify, minification, and simply concatenating plain JavaScript files.

CoffeeScript

The coffee method may be used to compile CoffeeScript into plain JavaScript. The coffee function accepts a string or array of CoffeeScript files relative to the resources/assets/coffee directory and generates a single app.js file in the public/js directory:

elixir(function(mix) {
    mix.coffee(['app.coffee', 'controllers.coffee']);
});

Browserify

Elixir also ships with a browserify method, which gives you all the benefits of requiring modules in the browser and using ECMAScript 6 and JSX.

This task assumes that your scripts are stored in resources/assets/js and will place the resulting file in public/js/main.js. You may pass a custom output location as an optional second argument:

elixir(function(mix) {
    mix.browserify('main.js');
});

// Specifying a specific output filename...
elixir(function(mix) {
    mix.browserify('main.js', 'public/javascripts/main.js');
});

While Browserify ships with the Partialify and Babelify transformers, you're free to install and add more if you wish:

npm install aliasify --save-dev

elixir.config.js.browserify.transformers.push({
    name: 'aliasify',
    options: {}
});

elixir(function(mix) {
    mix.browserify('main.js');
});

Babel

The babel method may be used to compile ECMAScript 6 and 7 and JSX into plain JavaScript. This function accepts an array of files relative to the resources/assets/js directory, and generates a single all.js file in the public/js directory:

elixir(function(mix) {
    mix.babel([
        'order.js',
        'product.js',
        'react-component.jsx'
    ]);
});

To choose a different output location, simply specify your desired path as the second argument. The signature and functionality of this method are identical to mix.scripts(), excluding the Babel compilation.

Scripts

If you have multiple JavaScript files that you would like to combine into a single file, you may use the scripts method.

The scripts method assumes all paths are relative to the resources/assets/js directory, and will place the resulting JavaScript in public/js/all.js by default:

elixir(function(mix) {
    mix.scripts([
        'jquery.js',
        'app.js'
    ]);
});

If you need to combine multiple sets of scripts into different files, you may make multiple calls to the scripts method. The second argument given to the method determines the resulting file name for each concatenation:

elixir(function(mix) {
    mix.scripts(['app.js', 'controllers.js'], 'public/js/app.js')
       .scripts(['forum.js', 'threads.js'], 'public/js/forum.js');
});

If you need to combine all of the scripts in a given directory, you may use the scriptsIn method. The resulting JavaScript will be placed in public/js/all.js:

elixir(function(mix) {
    mix.scriptsIn('public/js/some/directory');
});

Copying Files & Directories

The copy method may be used to copy files and directories to new locations. All operations are relative to the project's root directory:

elixir(function(mix) {
	mix.copy('vendor/foo/bar.css', 'public/css/bar.css');
});

elixir(function(mix) {
	mix.copy('vendor/package/views', 'resources/views');
});

Versioning / Cache Busting

Many developers suffix their compiled assets with a timestamp or unique token to force browsers to load the fresh assets instead of serving stale copies of the code. Elixir can handle this for you using the version method.

The version method accepts a file name relative to the public directory, and 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:

elixir(function(mix) {
    mix.version('css/all.css');
});

After generating the versioned file, you may use Laravel's global elixir PHP helper function within your views to load the appropriately hashed asset. The elixir function will automatically determine the name of the hashed file:

<link rel="stylesheet" href="{{ elixir('css/all.css') }}">

Versioning Multiple Files

You may pass an array to the version method to version multiple files:

elixir(function(mix) {
    mix.version(['css/all.css', 'js/app.js']);
});

Once the files have been versioned, you may use the elixir helper function to generate links to the proper hashed files. Remember, you only need to pass the name of the un-hashed file to the elixir helper function. The helper will use the un-hashed name to determine the current hashed version of the file:

<link rel="stylesheet" href="{{ elixir('css/all.css') }}">

<script src="{{ elixir('js/app.js') }}"></script>

BrowserSync

BrowserSync automatically refreshes your web browser after you make changes to your front-end resources. You can use the browserSync method to instruct Elixir to start a BrowserSync server when you run the gulp watch command:

elixir(function(mix) {
    mix.browserSync();
});

Once you run gulp watch, access your web application using port 3000 to enable browser syncing: http://homestead.app:3000. If you're using a domain other than homestead.app for local development, you may pass an array of options as the first argument to the browserSync method:

elixir(function(mix) {
    mix.browserSync({
    	proxy: 'project.app'
    });
});

Calling Existing Gulp Tasks

If you need to call an existing Gulp task from Elixir, you may use the task method. As an example, imagine that you have a Gulp 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));
});

If you wish to call this task from Elixir, use the mix.task method and pass the name of the task as the only argument to the method:

elixir(function(mix) {
    mix.task('speak');
});

Custom Watchers

If you need to register a watcher to run your custom task each time some files are modified, pass a regular expression as the second argument to the task method:

elixir(function(mix) {
    mix.task('speak', 'app/**/*.php');
});

Writing Elixir Extensions

If you need more flexibility than Elixir's task method can provide, you may create custom Elixir extensions. Elixir extensions allow you to pass arguments to your custom tasks. For example, you could write an extension like so:

// File: elixir-extensions.js

var gulp = require('gulp');
var shell = require('gulp-shell');
var Elixir = require('laravel-elixir');

var Task = Elixir.Task;

Elixir.extend('speak', function(message) {

    new Task('speak', function() {
        return gulp.src('').pipe(shell('say ' + message));
    });

});

// mix.speak('Hello World');

That's it! Notice that your Gulp-specific logic should be placed within the function passed as the second argument to the Task constructor. You may either place this at the top of your Gulpfile, or instead extract it to a custom tasks file. For example, if you place your extensions in elixir-extensions.js, you may require the file from your main Gulpfile like so:

// File: Gulpfile.js

var elixir = require('laravel-elixir');

require('./elixir-extensions')

elixir(function(mix) {
    mix.speak('Tea, Earl Grey, Hot');
});

Custom Watchers

If you would like your custom task to be re-triggered while running gulp watch, you may register a watcher:

new Task('speak', function() {
    return gulp.src('').pipe(shell('say ' + message));
})
.watch('./app/**');