quick-sip

Gulp build process tasks that provide watchify and sass compilation.

Project Layout

Here is an example project hierarchy that will work with the default settings:

project
  |-- package.json
  |-- gulpfile.js
  |-- app
       |-- app.js
       |-- app.scss
       |
       |-- scripts
       |      |-- chairModel.js
       |      |-- chairView.js
       |
       |-- styles
       |      |-- _chair.scss
       |      |-- _engraved.scss
       |
       |-- index.html

After running the build task, a "dist" directory will be created:

project
   | ...
   |-- dist
        |-- app.js
        |-- app.js.map
        |-- app.css
        |
        |-- index.html

app.js is the browserified application that app.js completely specifies. app.js.map is the source map for the browserified app.js bundle. app.scss is compiled by sass into app.css. index.html is copied from the source during the copy-resources task.

Executing Tasks

Your gulpfile.js only needs the following to give you access to the build tasks:

var gulp = require('gulp');
var tasks = require('quick-sip')(gulp);

exports.watch = tasks.watch;
exports.build = tasks.build;
exports.default = tasks.build;

With gulp 4 the tasks are exported as function and streams so each task exports a build and a watch function that can be run with gulp or exported as a task in your gulpfile.js.

If you need fine-grained control over which build and watch tasks to run you can get those from the exported tasks, see structure below.

{
  clean: <clean build task>,
  jshint: {
    build: <jshint build task>,
    watch: <jshint build task then watch task>
  },
  styles: {
    build: <styles build task>,
    watch: <styles build task then watch task>
  },
  copy: {
    build: <copy build task>,
    watch: <copy build task then watch task>
  },
  browserify: {
    build: <browserify task>,
    watch: <watchify task (includes initial browserify)>
  },
  build: <clean task, then all build tasks in parallel>,
  watch: <clean task, then all watch tasks in parallel>
}

• clean - Remove the contents of the dist directory.
• jshint - Runs gulp-jshint against the javascript files in the src directory.
• styles - Builds the styles to dist.
• copy - Copy the resources to dist (non-js and non-scss by default).
• browserify - Builds the javascript to dist.
• build - Builds the whole application; js, css, and resources.
• watch - Sets up watchify for your js, listens for scss changes, and handles other resource changes.

Transforming Browserify

Easy!

var gulp = require('gulp');
var buildProcess = require('quick-sip')(gulp, {
  browserify: {
    transforms: [
      { transform: 'aliasify', options: { global: true } },
      'hbsfy',
      yourCustomThroughTransform
    ]
  }
});

Defining Resource Exclusion Extensions

Easy!

var gulp = require('gulp');
var buildProcess = require('quick-sip')(gulp, {
  copy: {
    excludes: 'js|css|scss|hbs|frag|vert'
  }
});

Configuration Details

The configurations are specified as an optional property when creating the build processes.

var gulp = require('gulp');
var buildProcess = require('quick-sip')(gulp, options);

Options

The options are grouped by task with some top level defaults. Default values for each option is in (). Default options are also specified in the quick-sip/tasks/utils/options.js file.

Defaults

{
  taskPrefix: '',
  src: 'app',
  dist: 'dist',
  clean: {
    skip: false,
    dist: options.dist
  },
  browserify: {
    skip: false,
    root: './' + options.src + '/app',
    transforms: [],
    out: 'app.js',
    failOnError: false,
    debug: argv.type && argv.type !== 'production',
    dist: options.dist,
    skipUglify: argv.type && argv.type !== 'production'
  },
  styles: {
    skip: false,
    src: options.src,
    includes: [],
    root: options.src + '/app.scss',
    dist: options.dist
  },
  jshint: {
    src: './' + opts.src,
    globRelativeToSrc: '**/*.js',
    skip: true,
    stopOnFail: true,
    config: {}
  },
  copy: {
    skip: false,
    src: options.src,
    excludes: 'scss',
    dist: options.dist
  }
}

Note that the options. stuff is generated by merging the incoming options with the defaults. So copy.src will be 'dist' or the value you pass in for the dist property (which is overridden by the value you pass in for copy.src).

Base Options

[taskPrefix='']

Prefix used to prefix all task names to make them unique in your build. Not required if you only use quick-sip or if you do not define any overlapping tasks in gulp.

[src='app']

Default source directory to use, used as the root for each task's default src references (See task specific default options below).

[dist='dist']

Default distribution directory to use, used as the root for each task's default destination references (See task specific default options below).

Clean task options (task name: options.taskPrefix + 'clean'):

[clean.skip=false]

Whether the clean task should be skipped (true) or run (false).

[clean.dist=options.dist]

Defaults to the dist value in the base options. This is the directory that clean will delete when run.

JSHint task options (task name: options.taskPrefix + 'jshint'):

[src='./' + options.src]

This determines the directory to run the js linting on. Defaults to looking at the app directory.

[globRelativeToSrc='**/*.js']

This determines the files in the src directory to run the js linting on. Defaults to looking at all javascript files in the src directory.

[skip=false]

Whether the js lint (jshint) task should be skipped (true) or run (false).

[stopOnFail=true]

Whether warnings / errors should cause the task to fail or not.

[config={}]

The jshint configuration json to use. Empty object will use the default found in jshint-stylish.

Browserify task options (task name: options.taskPrefix + 'build-app'):

[browserify.skip=false]

Whether the browserify (build-app) task should be skipped (true) or run (false).

[browserify.root='./' + options.src + '/app']

The root javascript file to start browserify. With no configuration quick-sip will browserify '[your project]/app/app.js'.

[browserify.transforms=[]]

Collection of transforms to apply when running browserify. They can either be a value that browserify can consume natively (see browserify's transform option). Alternatively you can also specify options for the transform using

{
  transform: [transform name or function],
  options: [options to pass in for the transform]
}

[browserify.out='app.js']

The name of the file in the browserify.dist directory to save the browserified bundle. With no configuration quick-sip will save the resulting browserified file to '[your project]/dist/app.js'.

[browserify.failOnError=false]

Whether the browserify task should fail on the first error it encounters (true) and error the build or print out all failures it encounters and return success for the overall build.

[browserify.debug=argv.type && argv.type !== 'production']

Whether to run browserify in debug mode (true) or non-debug mode (false). Defaults to checking if the current environment is production (non-debug mode including not set) or some other environment (debug mode).

[browserify.dist=options.dist]

The distribution directory for the files generated by the browserify process. With no configuration quick-sip will save all browserified files to '[your project]/dist'.

[browserify.skipUglify=argv.type && argv.type !== 'production']

Whether to run uglify during the browserify process. Defaults to checking if the current environment is production (non-debug mode including not set) or some other environment (debug mode).

Styles task options (task name: options.taskPrefix + 'build-styles')

[styles.skip=false]

Whether the styles (build-styles) task should be skipped (true) or run (false).

[styles.includes=[]]

Array of paths to additional locations of files used by the sass plugin (see node-sass includePaths option).

[styles.root=options.src + '/app.scss']

The root file to run the sass on. With no configuration quick-sip will run sass on '[your project]/app/app.scss'.

[styles.dist=options.dist]

The destination directory for the resulting .css file. With no configuration quick-sip will save the css file to '[your project]/dist/app.css'.

Copy task options (task name: options.taskPrefix + 'copy-resources')

[copy.skip=false]

Whether the styles (copy-resources) task should be skipped (true) or run (false).

[copy.src=options.src]

The source directory to copy from. This can take either a single directory location or an array of locations. In the case you configure it with an array, it will use the single exclusion settings for ALL configured locations.

The task will copy all files matching:

[
  options.copy.src + '/**/*.*',
  '!' + options.copy.src + '/**/*.+(' + options.copy.excludes + ')'
]

[copy.excludes='scss']

This is a regex that matches any files you want excluded from the copy task. Example that excludes lots of file types: 'js|css|scss|hbs|frag|vert'

[copy.dist=options.dist]

The destination directory for the copied files. With no configuration quick-sip will save the files to '[your project]/dist/'.