Syrup

A collection of shared UI utilities and libraries leveraged by AI2 when developing interfaces.

Specifically, syrup provides:

• A series of gulp tasks for building a single-page client-side application.
• A collection of less styles. To see them in action, visit the demo.

Requirements

• nodejs >= 0.12.7 is required.

Installation

Install via npm:

npm install syrup

Gulp

Syrup includes a series of gulp tasks useful for building a single-page client-side application.

The gulp tasks provided by syrup can be initialized like so in your gulpfile.js:

// gulpfile.js
var gulp = require('gulp');
var syrup = require('syrup');
 
syrup.gulp.init(gulp);

A build can then be triggered from the terminal:

gulp build

Watch your project for changes dynamically and start a static HTTP server for previewing the result:

gulp watch-and-serve

Read about all of the available gulp tasks, the default project structure or the full API offered by the syrup.gulp.init().

LESS

To include the all of the less styles provide by syrup, simply add the following line to your less stylesheet:

@import '../../node_modules/syrup/less/syrup.less';

Gulp Tasks

Syrup provides the following tasks:

• clean

• Removes all build artifacts
• less
• Compiles and minifies LESS files to CSS files.
• jslint
• Lints JS files using jshint.
• js
• Bundles, minifies and obfuscates js files using browserify into a single, bundled script. Uses babel to provide support for ECMA6 features and ReactJS.
• assets
• Copies all assets into the build directory.
• html
• Copies the index.html file into the build directory after running the js, assets, and less tasks.
• build
• Builds the project by running the assets, jslint, js, less, and html tasks.
• watch
• Watches the project for changes and rebuilds the affected components as they occur.
• serve
• Runs an express HTTP serving serving the application.
• watch-and-serve
• Runs the watch and serve tasks.

Default Project Structure

The following project structure is expected by default, but can be changed via the paths parameter of syrup.gulp.init():

{
  // the location of your application's index.html file
  html: 'app/index.html',
  // the less files which will be watched for changes
  allLess: 'app/**/*.less',
  // the less entry-point
  less: 'app/main.less',
  // all js files to be linted using eslint
  jsLint: 'app/**/*.js',
  // the js entry-point
  js: 'app/app.js',
  // static assets (images, fonts, etc)
  assets: 'app/assets/**/*',
  // the location of build output
  build: 'build'
}

Gulp API

/**
 * Registers default gulp tasks.
 *
 * @param {object}  gulp                                The gulp library.
 * @param {object}  [options]                           Optional object definining configuration
 *                                                      parameters.
 * @param {boolean} [options.compressJs=true]           If true javascript will be minified.
 *                                                      Defaults to true. This causes the build
 *                                                      to become significantly slower.
 * @param {boolean} [options.sourceMaps=true]           Enables javascript source maps. Defaults
 *                                                      to true.
 * @param {boolean} [options.compressCss=true]          If true styles will be compressed.
 *                                                      Defaults to true.
 * @param {boolean} [options.detectGlobals=true]        Enables browserify global detection and
 *                                                      inclusion.  This is necessary for certain
 *                                                      npm packages to work when bundled for
 *                                                      front-end inclusion.  Defaults to true.
 * @param {boolean} [options.insertGlobals=false]       Enables automatic insertion of node
 *                                                      globals when preparing a javascript
 *                                                      bundler.  Faster alternative to
 *                                                      detectGlobals.  Causes an extra ~1000
 *                                                      lines to be added to the bundled
 *                                                      javascript.  Defaults to false.
 * @param {boolean} [options.disableJsLint=false]       Disables javascript linter. Defaults to false.
 * @param {boolean} [options.handleExceptions=false]    If an exception is encountered while
 *                                                      compiling less or bundling javascript,
 *                                                      capture the associated error and output
 *                                                      it cleanly. Defaults to false.
 * @param {string}  [options.jsOut]                     Overrides the default filename for the
 *                                                      resulting javascript bundle.  If not set
 *                                                      the javascript file will be the same name
 *                                                      as the entry point.
 * @param {boolean} [options.disableBabel=false]        Optionally disable babel, the es6 to es6
 *                                                      (and react JSX) transpiler.
 *                                                      See http://babeljs.io for more information.
 * @param {boolean} [options.enableStringify=false]     Optionally enable stringify, a browserify
 *                                                      transform that allows HTML files to be
 *                                                      included via require.
 * @param {number}  [options.port=4000]                 Optional port for the HTTP server started
 *                                                      via the serve task.  Defaults to 4000.
 * @param {object}  [configParameters]                  Optional map of configuration keys. If
 *                                                      set each key is searched for in the built
 *                                                      HTML and replaced with the corresponding
 *                                                      value.
 * @param {object}  [paths]                             Optional object defining paths relevant
 *                                                      to the project. Any specified paths are
 *                                                      merged with the defaults where these paths
 *                                                      take precedence.
 * @param {string}  paths.base                          The base directory of your project where
 *                                                      the gulpfile lives.  Defaults to the
 *                                                      current processes working directory.
 * @param {string}  paths.html                          Path to the project's HTML files.
 * @param {string}  paths.jsLint                        Path to the javascript files which should
 *                                                      be linted using eslint.
 * @param {string}  paths.js                            Javascript entry point.
 * @param {string}  paths.allLess                       Path matching all less files which should
 *                                                      be watched for changes.
 * @param {string}  paths.less                          The less entry-point.
 * @param {string}  paths.assets                        Path to the project's static assets.
 * @param {string}  paths.build                         Output directory where the build artifacts
 *                                                      should be placed.
 *
 * @returns {undefined} 
 */
syrup.gulp.init(gulp, options, configParameters, paths)