Version 3.0

Installation

In your project's root package.json file, update the Laravel Elixir version number to ^3.0.0, and run npm update.

{
  "dependencies": {
    "laravel-elixir": "^3.0.0"
  }
}

New

• True sequential tasks. With Laravel Elixir 2.0...

  mix.sass('one.scss').coffee('module.coffee').sass('two.scss');
  

  would trigger both of your Sass calls, before moving on to the CoffeeScript task. In some situations, this can create issues - where, for example, the second Sass call depends upon some file being created before it.

  With Elixir 3, we now have truly sequential tasks. Trigger, Sass, then Coffee, then Sass.

• More explicit logging. The Terminal will now detail the exact source and output files/directories that the current task is referencing (based upon your Gulpfile). http://d.pr/i/T8q3

• Easier configuration. Review the new config.js file. Note that any of these values may be updated by you. Of course, with Laravel, it's recommended that you stick to the defaults, but when you require, for example, a unique path to your assets or public directory, you may update these values, as needed.

  You may do so either in your main Gulpfile:

  elixir.config.publicPath = './public_html';
  

  Or, if you need to update multiple pieces of configuration, create an elixir.json file in your project, and insert a JSON object that should override any of the properties that have been set in config.js. For instance:

  {
      "publicPath": "./public_html",
  
      "css": {
          "outputFolder": "stylesheets"
      }
  }
  

Anything you add here will override the defaults. Also, note that you can modify plugin options or even your desired Browserify transformations from this file.

• Better File Validation. Ever fall into the trap of thinking you're compiling one file, only to realize that Elixir was trying to reference a different path? Maybe even a file that doesn't exist in your app? With Elixir 3.0, you'll now be alerted when a given source file does not exist. http://d.pr/i/15Hel

• Simpler Extensions. Creating an Elixir extension is now as simple as:

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

Fixes

• If you call an Elixir task, and provide a single file name as the source path, Elixir will use that file name as the output file name. In older versions, assuming you didn't provide an explicit output file path, Elixir would use a generic name, such as app.css. Now, as noted, it'll grab the source file name instead.

  mix.sass('foo.scss'); // compiles to ./public/css/foo.css
  

Breaking Changes

The main API for Elixir - the one you'll reference in your Gulpfile - is identical to past versions. However, both config paths and extension creation have changed.

• mix.version(path) no longer automatically adds the public path as the base directory. For instance, before, mix.version('css/foo.css') would look within "public/css/foo.css". Now, it'll look for "css/foo.css". Manually add "./public". (This way, any file may be versioned.)
• Refer to config.js to find the new configuration file. If you were modifying these values in your project, when you update Elixir to 3.0, ensure that you now reference the new path to the property setting.
• Any Laravel Elixir extensions will need to be updated to support version 3.0. Don't worry, it's quick to do so, and removes a lot of boilerplate.

Using that speak extension example from above, in Elixir 2.0, you would create it, 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() {
            return gulp.src('').pipe(shell('say ' + message));
        });

        return this.queueTask('speak')
                   .registerWatcher('speak', './app/**');

    });

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

With version 3.0, you'd do:

    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));
        })
        .watch('./app/**');

    });

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

Notice that you no longer need to personally call Gulp.task(). Elixir will handle that dynamically. Your only job is to create a new Elixir Task, and give it both a name and a definition. That definition should be a callback function that triggers Gulp, however is appropriate for your task. This is where you'll add your gulp.src('...') bits.

Always return the stream from this callback function. This is necessary to have truly sequential task calls.

Should you need to watch files for changes, and then subsequently trigger your task again, you may use the watch method on the Task object, as demonstrated above. Simply provide a regular expression, and Elixir will keep an eye on any of those files for changes.