gore-gulp

What does this package contain?

gore-gulp is a simple and universal Gulp configuration boilerplate for JavaScript projects.

gore-gulp supports React, React Native and Webpack based projects especially well.

It currently provides a set of predefined gulp tasks that suit most JavaScript projects. Instead of manually configuring gulp, you can just setup your project with gore-gulp using this one-liner (this would be your entire gulpfile.js if you do not need any non-js build steps. You'll have to handle those on your own):

// gulpfile.js

var gg = require("gore-gulp"),
    gulp = require("gulp");

gg(__dirname).setup(gulp);

...and then use predefined gulp tasks:

$ gulp lint # check your code using highly demading linter to prevent bugs
$ gulp test # perform regression tests to refactor with confidence
$ gulp webpack # pack your code to make it production-ready

gore-gulp takes advantage of package.json's "directories" feature. If you configure your package.json like this:

{
    "directories": {
        "dist": "./dist",
        "lib": "./my-package"
    }
}

It would make webpack task to look for all *.entry.js, *.entry.jsx and *.entry.coffee files inside ./my-package and output production-ready to the ./dist directory. For lib you can also configure multiple sources by placing an array of directories.

Why is gore-gulp so special?

gore-gulp is not like any traditional boilerplate. I maintain nearly 10 production websites and I find copying and pasting configuration files or even generating project stubs with tools like yeoman really painful (respect to yeoman, scaffolding just does not suit my needs). What I intend to achieve is to unite JavaScript tools and frameworks such as Webpack and React, and keep them in a package that requires no configuration.

If you want to use gore-gulp, all you need to do is to add this package to the devDependencies of your package.json.

$ npm install --save-dev gore-gulp

Feel free to open an issue if you’d like to see any changes.

Features

Vendor (non-NPM) libraries support

To support libraries from sources other than NPM—bower, for example—you need to specify an alias key in your package.json.

For example if you need to use bower edition of RxJS (for some strange reason) you can configure your project like this:

{
    "alias": {
        "rxjs": "bower_components/rxjs/dist/rx.all"
    },
    "directories": {
        "dist": "my-output-folder",
        "lib": "library-with-bower-components"
    },
    "name": "my-library-with-bower-components"
}

And then use it like this:

// library-with-bower-components/index.entry.js

import Rx from "rxjs";

Internally, alias key is an exposed webpack configuration field. Aliased paths are processed by gore-gulp before passing them to webpack to ensure that they are relative to base package directory (the one that holds package.json).

Examples

How to start a project with gore-gulp?

1. Add directories.dist and directories.lib sections to your package.json.

2. Setup your gulpfile.js with gore-gulp:

   var gg = require("gore-gulp"),
       gulp = require("gulp");
   
   gg(__dirname).setup(gulp);

3. Generate code using gulp webpack (use NODE_ENV=production for more optimizations).

Complete example

Visit the example directory for preconfigured project.

How can I use my local configuration file?

Currently it is only possible to override eslint settings by placing your .eslintrc file into the base project directory (the one that holds your package.json).

Can I attach my own plugin and why should I do that?

The goal of gore-gulp is to provide a configuration-less (!) development environment. But a centralized configuration is also easy to set up. If your organization uses common patterns among projects, you can create an NPM package with gore-gulp plugin and instead of configuring each project via copy-pasting you can attach your plugin.

The minimal plugin is a factory function that returns a gulp task.

// my-plugin.js

module.exports = {
    "dependencies": [],
    "factory": function (config, pckgPromise, gulpInstance) {
        return function () {
            // this function is going to be passed to the gulp.task call
            // config.baseDir is a directory of the host project (the one that uses gore-gulp)
            // pckgPromise resolves to host project's package.json contents
            // gulpInstance is the host project's gulp
        };
    },
    "name": "task-name"
};

// gulpfile.js

var myPlugin = require("my-plugin");

gg(__dirname).plugin(myPlugin).setup(gulp)

Invoking with CLI:

$ gulp task-name

How can I integrate gore-gulp into my editor?

Please check goreutils/gore-gulp-sublime-text for instruction on how to integrate gore-gulp with Sublime Text and benefit from global linter settings.

Can I still use plain gulp tasks?

Of course!

// gulpfile.js

gg(__dirname).setup(gulp);

gulp.task("sass", function () {
   return gulp.src("*.sass")
        .pipe(sass())
        .pipe(gulp.dest("assets"));
});

How to specify gore-gulp tasks dependencies?

// gulpfile.js

gg({
    "baseDir": __dirname,
    "dependencies": [
        "my-dependency"
    ]
}).setup(gulp);

gulp.task("my-dependency", function () {
    // this tasks is going to start before others
});

Can I autoload dependencies?

Sure, use package.json's provide key (it will also satisfy linter for the given variable):

// package.json

{
    "dependencies": {
        "bluebird": "2.x"
    },
    "provide": {
        "Promise": "bluebird"
    }
}

// index.entry.js

new Promise(function () {
    // no errors in this file
    // Promise is automatically included
});

Summary

The goal of this package is to provide a one-liner gulp configuration that enables the programmer to quickly start coding with the best practices of modern JavaScript.