Improve mix.combine() options - resolves laravel-mix#2465

Author: JeffreyWay

docs/concatenation-and-minification.md

@@ -1,45 +1,90 @@
 # Concatenation and Minification
 
+-   [Basic Usage](#basic-usage)
+    -   [Concatenate All Files in a Directory](#concatenate-all-files-in-a-directory)
+    -   [Concatenate All Matching Files in a Directory](#concatenate-all-matching-files-in-a-directory)
+    -   [Concatenate an Array of Files](#concatenate-an-array-of-files)
+    -   [Concatenate Scripts and Apply Babel Compilation](#concatenate-scripts-and-apply-babel-compilation)
+-   [File Minification](#file-minification)
+    -   [Minify a Single File](#minify-a-single-file)
+    -   [Minify an Array of File](#minify-an-array-of-file)
+
+Laravel Mix and webpack should take care of all the necessary module bundling and minification for you. However, you may have lingering legacy code or vendor libraries that need to remain separate from your core webpack bundle. Not a problem.
+
+For basic file concatenation and minification, Mix has you covered.
+
+### Basic Usage
+
+Consider the following Mix configuration file.
+
 ```js
-mix.combine(['src', 'files'], 'destination');
-mix.babel(['src', 'files'], destination);
-mix.minify('src');
-mix.minify(['src']);
+mix.combine(['one.js', 'two.js'], 'merged.js');
 ```
 
-If used properly, Laravel Mix and webpack should take care of all the necessary module bundling and minification for you. However, you may have some legacy code or vendor libraries that need to be concatenated and minified. Not a problem.
+This instructs Mix to merge - or concatenate - `one.js` and `two.js` into a single file, called `merged.js`. As always, during development, that merged file will remain uncompressed. However, when building for production, `merged.js` will of course be minified.
 
-### Combine Files
+> If it reads better to you, `mix.scripts()` and `mix.styles()` are aliases for `mix.combine()`.
 
-Consider the following snippet:
+#### Concatenate All Files in a Directory
 
 ```js
-mix.combine(['one.js', 'two.js'], 'merged.js');
+mix.combine('path/to/dir', 'all-files.js');
+
+// or:
+
+mix.scripts('path/to/dir', 'all-files.js');
+```
+
+#### Concatenate All Matching Files in a Directory
+
+```js
+mix.combine('path/to/dir/*.css', 'all-files.css');
+
+// or:
+
+mix.styles('path/to/dir/*.css', 'all-files.css');
 ```
 
-This will naturally merge `one.js` and `two.js` into a single file, called `merged.js`. As always, during development, that merged file will remain uncompressed. However, for production \(`export NODE_ENV=production`\), this command will additionally minify `merged.js`.
+#### Concatenate an Array of Files
 
-#### Combine Files With Babel Compilation
+```js
+mix.combine([
+    'path/to/dir/*.css',
+    'path/to/second/dir/*.css'
+], 'all-files.css');
+```
 
-If you need to concatenate JavaScript files that have been written in ES2015, you may update your `mix.combine()` call to `mix.babel()`. The method signature is identical. The only difference is that, after the files have been concatenated, Laravel Mix will perform Babel compilation on the result to transform the code to vanilla JavaScript that all browsers can understand.
+#### Concatenate Scripts and Apply Babel Compilation
+
+If you need to concatenate and then compile JavaScript files that have been written with the latest JavaScript syntax, you may either set the third argument of `mix.combine()` to `true`, or instead call `mix.babel()`. Other than the Babel compilation, both commands are identical. 
 
 ```js
+// Both of these are identical.
+mix.combine(['one.js', 'two.js'], 'merged.js', true);                                                     
 mix.babel(['one.js', 'two.js'], 'merged.js');
 ```
 
-### Minify Files
+### File Minification
 
 Similarly, you may also minify one or more files with the `mix.minify()` command.
 
+There are a few things worth noting here:
+
+1. `mix.minify()` will create a companion `*.min.{extension}` file. So minifying `app.js` will generate `app.min.js` within the same directory.
+2. As always, minification will only take place during a production build.
+3. There is no need to call `mix.combine(['one.js', 'two.js'], 'merged.js').minify('merged.js');`Just stick with the single `mix.combine()` call. It'll take care of both.
+
+> **Important**: Minification is only available for CSS and JavaScript files. The minifier will not understand any other provided file type.
+
+#### Minify a Single File
+
 ```js
 mix.minify('path/to/file.js');
-mix.minify(['this/one.js', 'and/this/one.js']);
 ```
 
-There are a few things worth noting here:
+#### Minify an Array of File
 
-1. This method will create a companion `*.min.ext` file. So minifying `app.js` will generate `app.min.js`.
-2. Once again, the minification will only take place during a production build. \(`export NODE_ENV=production`\).
-3. There is no need to call `mix.combine(['one.js', 'two.js'], 'merged.js').minify('merged.js');`Just stick with the single `mix.combine()` call. It'll take care of both.
+```js
+mix.minify(['this/one.js', 'and/this/one.js']);
+```
 
-> **Important**: Please note that minification is only available for CSS and JavaScript files. The minifier will not understand any other provided file type.

src/Assert.js

@@ -48,9 +48,15 @@ class Assert {
      * @param {File}   output
      */
     static combine(src, output) {
+        assert(
+            typeof src === 'string' || Array.isArray(src),
+            `mix.combine() requires a valid src string or array.`
+        );
+
         assert(
             output.isFile(),
-            'mix.combine() requires a full output file path as the second argument.'
+            'mix.combine() requires a full output file path as the second argument. Got ' +
+                output.path()
         );
     }
 

src/components/Combine.js

@@ -1,9 +1,9 @@
-let ConcatFilesTask = require('../tasks/ConcatenateFilesTask');
-let Assert = require('../Assert');
-let File = require('../File');
 let path = require('path');
-let collect = require('collect.js');
 let glob = require('glob');
+let File = require('../File');
+let Assert = require('../Assert');
+let { collect } = require('collect.js');
+let ConcatFilesTask = require('../tasks/ConcatenateFilesTask');
 
 class Combine {
     /**
@@ -14,41 +14,71 @@ class Combine {
     }
 
     /**
-     *
      * Register the component.
      *
-     * @param {*} src
-     * @param {string} output
+     * @param {String|Array} src
+     * @param {String} output
      * @param {Boolean} babel
      */
     register(src, output = '', babel = false) {
-        if (this.caller === 'babel') {
-            babel = true;
-        }
+        this.src = src;
+        this.output = output;
+        this.babel = babel || this.caller === 'babel';
 
         if (this.caller === 'minify') {
-            if (Array.isArray(src)) {
-                src.forEach(file => this.register(file));
+            this.registerMinify();
+        }
 
-                return this;
-            }
+        this.addTask();
+    }
 
-            output = src.replace(/\.([a-z]{2,})$/i, '.min.$1');
+    /**
+     * Register the minify task.
+     */
+    registerMinify() {
+        if (Array.isArray(this.src)) {
+            this.src.forEach(file => this.register(file));
         }
 
-        output = new File(output);
+        this.output = this.src.replace(/\.([a-z]{2,})$/i, '.min.$1');
+    }
 
-        Assert.combine(src, output);
+    /**
+     * Add a new ConcatFiles task.
+     */
+    addTask() {
+        this.output = new File(this.output);
 
-        if (typeof src === 'string' && File.find(src).isDirectory()) {
-            src = collect(glob.sync(path.join(src, '**/*'), { nodir: true }))
-                .except(output.relativePath())
-                .all();
-        }
+        Assert.combine(this.src, this.output);
 
-        let task = new ConcatFilesTask({ src, output, babel });
+        Mix.addTask(
+            new ConcatFilesTask({
+                src: collect(this.glob(this.src))
+                    .except(this.output.relativePath())
+                    .all(),
+                output: this.output,
+                babel: this.babel
+            })
+        );
+    }
 
-        Mix.addTask(task);
+    /**
+     * Find all relevant files matching the given source path.
+     *
+     * @param   {String|Array} src
+     * @returns {Array}
+     */
+    glob(src) {
+        return collect([].concat(src))
+            .flatMap(srcPath =>
+                glob.sync(
+                    File.find(srcPath).isDirectory()
+                        ? path.join(srcPath, '**/*')
+                        : srcPath,
+                    { nodir: true }
+                )
+            )
+            .all();
     }
 }
 

test/features/combine.js

@@ -1,41 +1,54 @@
 import test from 'ava';
-import eol from 'eol';
-import fs from 'fs-extra';
 import File from '../../src/File';
 import assert from '../helpers/assertions';
 import webpack from '../helpers/webpack';
 
 import '../helpers/mix';
 
-test('it combines a folder of scripts', async t => {
-    let output = `test/fixtures/app/dist/all.js`;
-
-    mix.scripts(`test/fixtures/app/src/js`, output);
+test('it accepts a src directory', async t => {
+    mix.scripts(
+        'test/fixtures/app/src/combine/foo',
+        'test/fixtures/app/dist/js/combined-scripts.js'
+    );
 
     await webpack.compile();
 
-    t.true(File.exists(output));
-
-    t.is(
-        "alert('another stub');\n\nalert('stub');\n",
-        File.find(output).read()
+    assert.fileMatchesCss(
+        'test/fixtures/app/dist/js/combined-scripts.js',
+        "alert('foo1');alert('foo2');",
+        t
     );
 });
 
-test('it can minify a file', async t => {
-    mix.js(`test/fixtures/app/src/js/app.js`, 'js').minify(
-        `test/fixtures/app/dist/js/app.js`
+test('it accepts a src wildcard', async t => {
+    mix.scripts(
+        'test/fixtures/app/src/combine/foo/*.js',
+        'test/fixtures/app/dist/js/combined-scripts.js'
     );
 
     await webpack.compile();
 
-    t.true(File.exists(`test/fixtures/app/dist/js/app.min.js`));
+    assert.fileMatchesCss(
+        'test/fixtures/app/dist/js/combined-scripts.js',
+        "alert('foo1');alert('foo2');",
+        t
+    );
+});
 
-    assert.manifestEquals(
-        {
-            '/js/app.js': '/js/app.js',
-            '/js/app.min.js': '/js/app.min.js'
-        },
+test('it accepts a src array of wildcards', async t => {
+    mix.scripts(
+        [
+            'test/fixtures/app/src/combine/foo/*.js',
+            `test/fixtures/app/src/combine/bar/*.js`
+        ],
+        'test/fixtures/app/dist/js/combined-scripts.js'
+    );
+
+    await webpack.compile();
+
+    assert.fileMatchesCss(
+        'test/fixtures/app/dist/js/combined-scripts.js',
+        "alert('foo1');alert('foo2');alert('bar1');alert('bar2');",
         t
     );
 });
@@ -68,17 +81,10 @@ test('it compiles JS and then combines the bundles files.', async t => {
 test('it concatenates a directory of files, copies the output to a new location, and then minifies it in production mode', async t => {
     Config.production = true;
 
-    // Setup
-    new File('test/fixtures/app/src/combine/one.js')
-        .makeDirectories()
-        .write("alert('one')");
-
-    new File('test/fixtures/app/src/combine/two.js').write("alert('two')");
-
     mix.scripts(
         [
-            `test/fixtures/app/src/combine/one.js`,
-            `test/fixtures/app/src/combine/two.js`
+            `test/fixtures/app/src/combine/foo/one.js`,
+            `test/fixtures/app/src/combine/foo/two.js`
         ],
         'test/fixtures/app/dist/output/combined-scripts.js'
     );
@@ -90,28 +96,53 @@ test('it concatenates a directory of files, copies the output to a new location,
 
     await webpack.compile();
 
-    let expected = 'alert("one"),alert("two");' + eol.auto;
+    assert.fileMatchesCss(
+        'test/fixtures/app/dist/js/combined-scripts.js',
+        'alert("foo1"),alert("foo2");',
+        t
+    );
+});
 
-    t.is(
-        expected,
-        File.find('test/fixtures/app/dist/js/combined-scripts.js').read()
+test('it minifies a file', async t => {
+    mix.js(`test/fixtures/app/src/js/app.js`, 'js').minify(
+        `test/fixtures/app/dist/js/app.js`
     );
 
-    // Clean up
-    fs.removeSync('test/fixtures/app/src/combine');
+    await webpack.compile();
+
+    t.true(File.exists(`test/fixtures/app/dist/js/app.min.js`));
+
+    assert.manifestEquals(
+        {
+            '/js/app.js': '/js/app.js',
+            '/js/app.min.js': '/js/app.min.js'
+        },
+        t
+    );
 });
 
-test('mix.combine/scripts/styles/babel()', t => {
-    t.deepEqual(mix, mix.combine([], 'dist/js/combined.js'));
+test('it minifies an array of files', async t => {
+    mix.minify([
+        `test/fixtures/app/src/combine/foo/one.js`,
+        `test/fixtures/app/src/combine/foo/two.js`
+    ]);
 
-    t.is(1, Mix.tasks.length);
+    await webpack.compile();
 
-    t.deepEqual(mix, mix.scripts([], 'dist/js/combined.js'));
-    t.deepEqual(mix, mix.babel([], 'dist/js/combined.js'));
-});
+    t.true(File.exists(`test/fixtures/app/src/combine/foo/one.min.js`));
+    t.true(File.exists(`test/fixtures/app/src/combine/foo/two.min.js`));
 
-test('mix.minify()', t => {
-    t.deepEqual(mix, mix.minify('dist/js/minify.js'));
+    assert.manifestEquals(
+        {
+            '/test/fixtures/app/src/combine/foo/one.min.js':
+                '/test/fixtures/app/src/combine/foo/one.min.js',
+            '/test/fixtures/app/src/combine/foo/two.min.js':
+                '/test/fixtures/app/src/combine/foo/two.min.js'
+        },
+        t
+    );
 
-    t.is(1, Mix.tasks.length);
+    // Clean Up
+    File.find(`test/fixtures/app/src/combine/foo/one.min.js`).delete();
+    File.find(`test/fixtures/app/src/combine/foo/two.min.js`).delete();
 });

test/fixtures/app/src/combine/bar/one.js

@@ -0,0 +1 @@
+alert('bar1');

test/fixtures/app/src/combine/bar/two.js

@@ -0,0 +1 @@
+alert('bar2');