Home Reference Source Repository

gulp-bundlerify

(gulp-) Bundlerify it's something between a generator and a boilerplate for ES6 projects.

Build Status Coverage Status Documentation Status Dependencies status Dev dependencies status

It uses Browserify, Babel, Watchify and BrowserSync (among others) to build your ES6 project with just a couple of lines, but at the same time, it's also highly customizable: You can inject your own dependencies and tasks very easily.

I now it's nothing new or special, but every time I started a new project I had 3 issues:

Well, the solution:

Information

- -
Package gulp-bundlerify
Description Something between a generator and a boilerplate for ES6 projects
Node Version >= v0.12.6 (You need >= v4.0.0 for the tests)

Installation

You can install gulp-bundlerify using npm.

npm install gulp-bundlerify --save_dev
npm install babel-preset-es2015 --save_dev

Yes, you need to install an extra package, because since version 6.0, Babel requires this package to compile your code ES5 compatible, and, for some reason, it can't be used from inside Bundlerify.

Usage

// Import your Gulp
const gulp = require('gulp');
// Import Bundlerify
const Bundlerify = require('gulp-bundlerify');

// Create the instance and call the .tasks() method.
new Bundlerify(gulp, {
    mainFile: './demo/index.js',
    browserSyncBaseDir: './demo/',
}).tasks();

Just with that you have all the tasks Bundlerify adds and the basic settings to run your project:

Ok, that's just the basic usage, now lets review all the possible settings...

Build generation

new Bundlerify(gulp, {
    mainFile: './index.js',
    dist: {
        file: 'build.js',
        dir: './dist/'
    },
}).tasks();

Compile to ES5

new Bundlerify(gulp, {
    es5: {
        origin: './src/**/*',
        dir: './es5/',
    },
}).tasks();

Watchify options

new Bundlerify(gulp, {
    watchifyOptions: {
        debug: true,
        fullPaths: true,
    },
}).tasks();

Browserify docs

BrowserSync options

new Bundlerify(gulp, {
    browserSyncOptions: {
        server: {
            baseDir: './',
            directory: true,
            index: 'index.html',
            routes: {
                '/src/': './src/',
                '/dist/': './dist/',
            },
        },
    }
}).tasks();

BrowserSync docs

Babelify options

new Bundlerify(gulp, {
    babelifyOptions: {
        presets: ['es2015'],
    },
}).tasks();

Babelify docs

Polyfills

new Bundlerify(gulp, {
    polyfillsEnabled: false,
    polyfills: [
        'whatwg-fetch/fetch',
        'core-js/fn/symbol',
        'core-js/fn/promise',
    ],
}).tasks();

Uglify

new Bundlerify(gulp, {
    uglify: false,
}).tasks();

Lint

new Bundlerify(gulp, {
    lint: {
        jscs: true,
        eslint: true,
        target: ['./src/**/*.js'],
    }
}).tasks();

Check the Extras section for more information about JSCS and ESLint.

Docs

new Bundlerify(gulp, {
    esdocOptions: {
        source: './src',
        destination: './docs',
        plugins: [
            {name: 'esdoc-es7-plugin'},
        ],
    }
}).tasks();

If you have your ESDoc configuration on a esdoc.json, you can tell Bundlerify to get your settings from there by giving the name of your file to the esdocOptions key:

new Bundlerify(gulp, {
    esdocOptions: 'esdoc.json'
}).tasks();

Note: You'll need to have an esdoc.json file if you want to use the uploadDocs task.

Check the Extras section for more information about ESDoc.

ESDoc docs (:P)

Unit testing

new Bundlerify(gulp, {
    jestOptions: {
        target: '.',
        collectCoverage: true,
        preprocessorIgnorePatterns: ['/node_modules/', '/dist/', '/es5/']
    }
}).tasks();

Two things to have in mind while using this:

new Bundlerify(gulp, {
    jestOptions: 'jest.json'
}).tasks();

And if you are migrating and you already have your Jest settings in your package.json, no problem! Bundlerify will automatically detect it and extract your settings from the jest property:

{
    "name": "gulp-bundlerify",
    "repository": "homer0/gulp-bundlerify",
    "license": "MIT",
    "jest": {
        "collectCoverage": true,
        "collectCoverageOnlyFrom": {
            "src/index.js" : true
        },
    },
    "main": "dist/index.js"
}

and...

new Bundlerify(gulp, {
    jestOptions: 'package.json'
}).tasks();

Jest docs

Tasks

new Bundlerify(gulp, {
    tasks: {
        serve: 'server',
        lint: {
            name: 'linter',
            deps: ['clean'],
        },
        build: {
            name: 'builder',
            deps: ['super-clean', 'mega-clean'],
            method: (task, callback) => {
                doSomething();
                task();
                callback();
            },
        },
        docs: false,
    },
}).tasks();

The tasks setting is, maybe, the "most" complex of the settings, but allows you to customize everything related to the tasks Bundlerify creates.

This setting is an object with six keys, one per each task Bundlerify creates: build, serve, clean, lint, es5, cleanEs5 and docs (you can see a brief description of each one at the beginning of this section); and you can do four things with the tasks:

- Disable

To disable a task, you just set the value of its key to false:

new Bundlerify(gulp, {
    tasks: {
        docs: false,
    },
}).tasks();

- Rename

You have two ways of doing this: You can set the value of its key to the new name:

new Bundlerify(gulp, {
    tasks: {
        docs: 'documentation',
    },
}).tasks();

Or you can use an object with the name key on it.

new Bundlerify(gulp, {
    tasks: {
        docs: {
            name: 'doc-build',
        },
    },
}).tasks();

- Adding task dependencies

If you want to add extra dependencies tasks to one of Bundlerify tasks, you can use an object with the deps keys:

new Bundlerify(gulp, {
    tasks: {
        docs: {
            deps: ['some-dependant-task'],
        },
    },
}).tasks();

- Overwriting the task functionality

If you want to change the way the task works, you can use an object with the key method for a function that receives two arguments: The original task function and the callback function the Gulp task sends.

new Bundlerify(gulp, {
    tasks: {
        build: {
            method: (task, callback) => {
                doSomething();
                task();
                callback();
            },
        },
    },
}).tasks();

Running a callback before every task

new Bundlerify(gulp, {
    beforeTask: (task, instance) => {
        // ... do something
    }
}).tasks();

This is a utility callback that runs before executing every task. It can be used to change the instance settings depending on the task that it's about to run.

Dependencies

Bundlerify uses seventeen(*) module dependencies and each and every one of them can be overwritten with a simple getter method.

1 - Watchify

This is used to update your Browserify build any time you make a change. This plays along with BrowserSync perfectly :). You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.watchify = myCustomWatchify;

2 - Browserify

This generates one single build package with all the required modules of your project. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.browserify = myCustomBrowserify;

3 - Babelify

It transforms your ES6 code with Babel so Browserify can create a build. Babelify it's also used with vinyl-transform by the es5 task to compile the separated files. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.babelify = myCustomBabelify;

4 - vinyl-source-stream

Creates a text stream of the Browserify build so it can be modified on the Gulp pipe. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.vinylSourceStream = myCustomVinylSourceStream;

5 - vinyl-transform

Allows the use of a Browserify transform plugins on a regular Gulp stream, and thanks to that, Bundlerify can re use Babelify to compile each individual file with the es5 task. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.vinylTransform = myCustomVinylTransform;

6 - BrowserSync

Creates a test server for your project and refreshes the page every time your build it's updated (which is updated thanks to Watchify). You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.browserSync = myCustomBrowserSync;

7 - rimraf

It's the node version of rm -rf ... and it's used to clean the distribution directory before doing a new build. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.rimraf = myCustomRimRaf;

8 - gulp-util

A set of utility function for Gulp. Bundlerify uses it to log Gulp-like errors on the console. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpUtil = myCustomGulpUtil;

9 - gulp-if

A utility module that runs in the pipe and execute some actions depending on a boolean balue... an if for .pipe. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpIf = myCustomGulpIf;

10 - gulp-streamify

Force some plugins to work with Gulp streams. Bundlerify uses it for gulp-uglify. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpStreamify = myCustomGulpStreamify;

11 - gulp-uglify

Minifies and uglifies the build file. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpUglify = myCustomGulpUglify;

12 - gulp-jscs

Lint your project with JSCS. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpJSCS = myCustomGulpJSCS;

13 - gulp-eslint

Lint your project with ESLint. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.gulpESLint = myCustomGulpESLint;

14 - ESDoc

Generates your project documentation. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.esdoc = myCustomESDoc;

ESdoc it's special because it also uses a publisher module, and by default, Bundlerify requires the one inside the ESDoc package (esdoc/out/src/Publisher/publish but you can inject your own version by doing this:

const b = new Bundlerify(gulp);
esdocPublisher = myCustomESDocPublisher;

15 - esdoc-uploader

This is a plugin I made and that allows Bundlerify to connect with the ESDoc Hosting API in order to generate your project documentation. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.esdocUploader = myCustomUploader;

16 - jest-cli

Runs your unit tests suite. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.jest = myCustomJest;

17 - through2

A wrapper for streams that allows the plugin to run jest-cli with a stream rather than running the cli command. You can inject your own version by doing this:

const b = new Bundlerify(gulp);
b.through = myCustomThrough;

*: Note

There are five other dependencies that can't be "injected", but that's because the Bundlerify doesn't use them directly:

Extras

JSCS

JSCS is a code style linter for programmatically enforcing your style guide. You can configure JSCS for your project in detail using over 150 validation rules, including presets from popular style guides like jQuery, Airbnb, Google, and more.

If you want a quick start, you can copy the .jscscr file from this repository and put it on the root of your project, then just run the lint task. Feel free to modify your .jscsrc with your own rules and presets.

JSCS overview.

ESLint

The pluggable linting utility for JavaScript and JSX.

The short version, it's like JSHint, but it supports plugins :). Like with JSCS, you can copy the .eslintrc file from this repository and run the lint task.

ESDoc

ESDoc is a documentation generator for JavaScript(ES6).

that pretty much sums it up, it's a doc generator. Unlike JSCS and ESLint, you don't necessarily need an .esdocrc file, well it uses an esdoc.json, but you can set the configuration using the Bundlerify esdocOptions setting option. As mentioned on the Docs section of this file, if you need/use an external file for the configuration, you can give Bundlerify the name of your file as value for esdocOptions and it will automatically retrieve those values.

Jest

Painless JavaScript Unit Testing

Jest is a unit tests suite Facebook built on top of Jasmine and that it's intended to test ES6 and React applications. It's really easy to configure and as you may noticed, Bundlerify not only provides support for your project Jest tests, but it also uses itself for its own unit tests.

Development

Install Git hooks

./hooks/install

npm tasks

Version History

1.0.3

1.0.2

1.0.0 and 1.0.1

Initial version. The reason I made an empty release was because I published it to early in npmjs and I needed to refresh it.

License

MIT. License file.