gulp-mux

Gulp-mux is a utility for registering and running tasks using gulp based on simple javascript functions requiring dynamically generated parameters. It was written for using gulp with generator-mcfly but is useful in any project that employs gulp to manage several distribution targets or sub-apps. It contains a submodule to allow the user to specify which targets they want to use when running a given task from the command line, as well as the mode they want to use when running it, i.e. dev or prod.

Usage

Require the module from your gulpfile using

var gmux = require('gulp-mux');

Motivation

This tool allows the user to run gulp tasks for files with different flags as suffixes in their filenames, indicating that there are multiple client-side sub-apps built in the same project tree. A single project may have a mobile app to be compiled with cordova, a web app that isn't, and others such as an interactive API visualizer. All of them talk to the same back-end and they often require similar front-end code, so building them side-by-side in the same client folder can leverage pre-existing folder structure and keep your code reuse high. The downside to this approach is that standard taskrunners like gulp, as well as many of the common tasks they use like style, browserify, or browsersync will not know the difference between the various apps if they are in the same place. gulp-mux was written to handle these cases by instructing gulp tasks how to run selectively on only the files associated with the desired targets.

How it works

gulp-mux inspects the root level of your client folder for a number of files that match index*.html. It makes the assumption that each of the user's intended sub-apps has its own index-<sub-app-name>.html in that location. Thus a project with mobile, web, and apitool sub-apps is expected to have a client folder that looks like this:

client
├── ...
├── index-apitool.html
├── index-mobile.html
├── index-web.html
├── index.html
└── ...

NB: This is part of what is scaffolded by yo mcfly:target

Once gulp-mux has inspected the client folder it finds that four targets are available: the three mentioned previously, apitool, mobile, and web, as well as the default target app from index.html. Running getAllTargets gives us these targets in an array:

gmux.targets.getAllTargets(); // -> ['apitool', 'app', 'mobile', 'web']

The app target is the default target that gulp-mux expects when no target suffix is provided in the filename. Otherwise it works exactly like any other target available.

Now that it has established which target are available, gulp-mux will be able to selectively create and run gulp tasks that work with only the files associated with the specified targets.

Example Setup

Follow these steps to set up a simple copy task that uses gulp-mux. Let us assume we have built already a gulpfile witha a simple copy task to copy everything in our source folder to our destination folder:

'use strict';
var gulp = require('gulp');

var srcFolder = 'source/*',
    destFolder = 'destination';

gulp.task('copy', function() {
    gulp.src(srcFolder)
        .pipe(gulp.dest(destFolder));
});

The first thing we need to do is to create a constants object holding the srcFolder and destFolder. The issue is that gulp does not accept parameters when you run a task, because it is run from the command line. But because it's javascript, we can decouple the gulp task itself from the functions that it is running:

var constants = {
    srcFolder: 'source/*',
    destFolder: 'destination'
};

var taskCopy = function(constant) {
    gulp.src(constant.srcFolder)
        .pipe(gulp.dest(constant.destFolder));
};

// add your top gulp tasks here
gulp.task('copy', function() {
    taskCopy(constants);
});

The benefit of this is that now we can reuse the same taskCopy function with different sets of parameters:

var constants1 = {
    srcFolder: 'source-one/*',
    destFolder: 'destination-one'
};
var constants2 = {
    srcFolder: 'source-two/*',
    destFolder: 'destination-two'
};

var taskCopy = function(const) {...};

gulp.task('copy:all', function() {
    taskCopy(constant1);
    taskCopy(constant2);
});

This is all good and simple and even allows us to run targeted copy tasks independenty, but we still are hard-coding the various constants. Let's address this by refactoring our constants object to use a dynamically templated target:

var constants = {
    srcFolder: 'source-{{target}}/*',
    destFolder: 'destination-{{target}}'
};

Now we can use gulp-mux's resolveConstants method to fill in our template:

gmux.resolveConstants(constants, {'target': 'one'}); 
    // -> {srcFolder: 'source-one', destFolder: 'destination-one'}

And finally we can bring this back to our copy:all task using a forEach to iterate over all of the sources and destinations we require.

var gmux = require('gulp-mux');

var constants = {
    srcFolder: 'source-{{target}}/*',
    destFolder: 'destination-{{target}}'
};

var targets = ['one', 'two'];

var taskCopy = function(const) {...};

gulp.task('copy:all', function() {
    targets.forEach(function(target) {
        taskCopy(gmux.resolveConstants(constants, {'template': target}));
    });
});

Finally let's refactor our copy task one more time to use gulp-mux's createAndRunTasks method.

var gmux = require('gulp-mux');

var constants = {...};
var targets = ['one', 'two'];
var taskCopy = function(const) {...};

gulp.task('copy:all', function() {
    return gmux.createAndRunTasks(gulp, taskCopy, 'copy', targets, '', constants);
});

Now our final gulpfile should look like this.

'use strict';
var gulp = require('gulp');
var gmux = require('gulp-mux');

var constants = {
    srcFolder: 'source-{{targetName}}/*',
    destFolder: 'destination-{{targetName}}'
};
var targets = ['one', 'two'];
var taskCopy = function(constant) {
    gulp.src(constant.srcFolder)
        .pipe(gulp.dest(constant.destFolder));
};

gulp.task('copy:all', function() {
    return gmux.createAndRunTasks(gulp, taskCopy, 'copy', targets, '', constants);
});

When we stick it into a project tree that looks like this:

~/dev/Yoobic/copyProject > tree
.
├── destination-one
├── destination-two
├── gulpfile.js
├── node_modules
├── ├── gulp
│   │   └── ...
│   └── gulp-mux
│       └── ...
├── source-one
│   └── copyme
└── source-two
    └── copymetoo

We can run gulp copy:all from the command line and see that our files have been successfully copied.

~/dev/Yoobic/copyProject > gulp copy:all
[15:17:19] Using gulpfile ~/dev/Yoobic/mux-test/gulpfile.js
[15:17:19] Starting 'copy:all'...
[15:17:19] Starting 'copy:T4Nc1'...
[15:17:19] Finished 'copy:T4Nc1' after 5.83 ms
[15:17:19] Starting 'copy:1nDM4'...
[15:17:19] Finished 'copy:1nDM4' after 1.21 ms
[15:17:19] Finished 'copy:all' after 12 ms
~/dev/Yoobic/copyProject > tree
.
├── destination-one
│   └── copyme
├── destination-two
│   └── copymetoo
├── gulpfile.js
├── node_modules
├── ├── gulp
│   │   └── ...
│   └── gulp-mux
│       └── ...
├── source-one
│   └── copyme
└── source-two
    └── copymetoo

API

The following assumes you required the module as decribed in the Usage section.

gmux.targets Methods

setClientFolder(path)

Set the client folder where the available targets live.

This function tells gulp-mux which folder contains index*.html files that define which targets are available. If a client folder is not provided, the module will assume that the client folder is called client and is located in the root directory of your project.

targetToSuffix(targetname)

Gets the suffix name of a specific target

basenameToTarget(basename)

Gets the target name of a target file

getAllTargets()

Inspect the client folder set with setClientFolder for files with a name that matches index-<target>.html. An array of <target> names is returned.

This function returns an array containing a list of all of the avaialable target names found in the client folder that you specified.

askForMultipleTargets(taskname)

Create and return the yargs object containing the multiple targets provided on the command line with -t and the mode if provided with -m.

Instructions for askForMultipleTargets

askForSingleTarget(taskname)

Create and return the yargs object containing the single target provided on the command line with -t and the mode if provided with -m.

Instructions for askForSingleTarget

gmux Methods

resolveConstants(constants, templateObj)

Resolve the passed constants object with the target

Instructions for resolveConstants

createAndRunTasks(gulp, fn, taskname, targets, mode, constants, cb)

Composes the createTask and runTask functions

Instructions for createAndRunTasks

Testing

To run unit test for the yeoman project use the following command:

gulp test

If you just want to run mocha and are not interested yet in linting your files you can run:

gulp mocha

If you just want to run some specific unit test use:

mocha test/app.test.js -r test/helpers/globals.js

This will tell mocha to run only the tests located in test/app.test.js (The -r option is necessary here to add global configuration file for mocha, when using gulp the globals.js is added automatically)

Changelog

Recent changes can be viewed on Github on the Releases Page

License