typhonjs-core-gulptasks

Provides common shared Gulp tasks for TyphonJS and beyond for those using JSPM / SystemJS. By packaging all common Gulp tasks as a NPM module this fascilitates sharing the tasks across several projects / repos having one authoritative and versioned source for these tasks and all dependencies. Various JSPM & NPM CLI functions are wrapped as tasks allowing execution from IDEs which support Gulp.

Please note as of the 0.6.0 release that dependencies for the tasks defined below are no longer bundled with typhonjs-core-gulptasks and need to be separately installed for the associated tasks to be loaded. For seamless integration for ESDoc and ESLint tasks consider loading typhonjs-npm-build-test as a dev dependency.

For the latest significant changes please see the CHANGELOG.

The following tasks are available and defined in typhonjs-core-gulptasks with the following categories:

• electron:

  • electron-package-<platform>-<arch> - Invokes electron-packager with the options from .electronrc in the root path. Default values are provided for platform -> 'process.platform', arch -> 'process.arch', source -> '.' and out -> 'build' if not supplied. For options to provide in .electronrc please see: https://www.npmjs.com/package/electron-packager#programmatic-api

  • electron-start - Spawns electron . starting the app defined in package.json->main entry in the root path.

  • electron-start-debug - Spawns electron --debug=5858 . starting the app defined in package.json->main entry in the root path.

• esdocs:

  • esdocs - Creates ES6 documentation with ESDocs via esdoc which must be installed separately outputting to the location specified by .esdocrc or esdoc.json. Consider using typhonjs-npm-build-test as a dev dependency for esdoc-plugin-jspm and esdoc-plugin-extends-replace support.

• eslint:

  • eslint - Runs ESLint via eslint using .eslintrc outputting to console and failing on any errors. Consider using typhonjs-npm-build-test as a dev dependency which includes eslint as a dependency.

• jspm:

  • jspm-bundle - Creates one or more bundles defined in ./config/bundle-config.json or ./config/bundle-config-travis.json (Add --travis argument to run minimal in memory bundle op for Travis CI.). When running from the command line you may use gulp jspm-bundle --bundleConfig=<path/to/custom/config.json> to use a specific customized bundle configuration.

  • jspm-clear-config - Removes all paths and map entries that may be populated in the primary JSPM config file. Performs a git commit if the config file was modified.

  • jspm-dl-loader - Executes jspm dl-loader via JSPM CLI.

  • jspm-inspect - Executes jspm inspect via JSPM CLI.

  • jspm-install - Executes jspm install via JSPM CLI.

• jspm-test:

  • jspm-test-basic - Sets process.env.TRAVIS for in memory bundling and runs eslint and jspm-bundle tasks for basic testing.

  • jspm-test-basic-git-push - Verifies the build by running jspm-test-basic and on success executes git push.

• npm:

  • npm-install - Executes npm install via NPM CLI.

  • npm-list-depth-0 - Executes npm list --depth=0 via NPM CLI.

  • npm-outdated - Executes npm outdated via NPM CLI.

  • npm-uninstall - Executes npm uninstall via NPM CLI.

  • npm-update - Executes npm update via NPM CLI.

  • npm-update-dev - Executes npm update --dev via NPM CLI.

• npm-scripts:

  • npm-run-<script name> - Creates Gulp tasks dynamically generated from script entries found in package.json in the rootPath. Executes npm run <script name> via NPM CLI.

Importing and using typhonjs-core-gulptasks is easy and streamlined.

First include it as an entry in devDependencies in package.json:

{
  ...
  
  "devDependencies": {
    "gulp": "^3.9.0",
    "jspm": "^0.16.0",
    "typhonjs-core-gulptasks": "^0.6.0",
    "typhonjs-npm-build-test": "^0.1.0"
  }
}

Then create a minimal gulpfile.js:

var gulp = require('gulp');

// Require all `typhonjs-core-gulptasks`; please note that typhonjs-core-gulptasks is now ES6 so `default` is required.
require('typhonjs-core-gulptasks').default(gulp, { rootPath: __dirname, srcGlob: './src/**/*.js' });

or better yet if using Babel / typhonjs-npm-build-test create a minimal ES6 gulpfile.babel.js:

import gulp          from 'gulp';
import gulpTasks     from 'typhonjs-core-gulptasks';

// Import all tasks and set `rootPath` to the base project path and `srcGlob` to all JS sources in `./src`.
gulpTasks(gulp, { rootPath: __dirname, srcGlob: ['./src/**/*.js'] });

Required options:

• rootPath - The root path where package.json is located for the given project that may contain JSPM directives.

• srcGlob - Defines a string or array of strings for the location of local sources to be manipulated by the following tasks: eslint.

Optional configuration parameters:

configDir - The directory where configuration files for various tasks such as jspm-bundle are stored; default (./config).

• excludeTasks - An array of strings which specifies particular categories of tasks to exclude.

• importTasks - An array of strings which specifies which categories of tasks to load. This allows only exposing certain tasks that are relevant for a given project. For instance several TyphonJS Node packages only use eslint and npm. Available task categories include: 'electron', 'esdoc', 'eslint', 'jspm', 'jspm-test', 'npm' and 'npm-scripts'.

---

The Electron tasks require that NPM modules electron-packager and electron-prebuilt are installed in addition to an .electronrc configuration file located in the root path. .electronrc contains optional parameters for invoking electron-packager. Default values are provided for platform -> 'process.platform', arch -> 'process.arch', source -> '.' and out -> 'build' if not supplied. If the above requirements are met these tasks will be available. For options to provide in .electronrc please see: https://www.npmjs.com/package/electron-packager#programmatic-api

For a complete example please see: electron-backbone-es6-localstorage-todos

The esdoc task requires a valid .esdocrc or esdoc.json configuration file file in the root project path.

The eslint task requires a valid .eslintrc file in the root project path.

The jspm-bundle task requires two configuration files to be defined in ./config:

• ./config/bundle-config.json - Provides the main bundle configuration.

• ./config/bundle-config-travis.json - Provides the testing / Travis bundle configuration which is used for an in memory bundle op by SystemJS Builder.

You may use comments in the bundle-config JSON files as they are stripped.

The following is an example entry:

{
  "entryPoints":
  [
    {
      "buildType": "buildStatic",         // (Optional) 'buildStatic' is the default; use 'bundle' for non-SFX build.
      "inMemoryBuild": false              // (Optional) Indicates in memory build; may omit `dest<X>` entries.
      "destBaseDir": "./dist",            // Root destination directory for bundle output.
      "destFilename": "<filename>.js",    // Destination bundle file name.
      "formats": ["amd", "cjs", "umd"],   // Module format to use / also defines destination sub-directory.
      "mangle": false,                    // Uglify mangle property used by SystemJS Builder.
      "minify": false,                    // Minify property used by SystemJS Builder.
      "src": "<dir>/<filename>.js",       // Entry source point for SystemJS Builder
      "extraConfig":                      // (Optional) Defines additional JSPM config parameters to load after
      {                                   // ./config.js is loaded. Provide a string or array of strings and they
        "meta":                           // will be interpreted as an additional configuration file styled like
        {                                 // `config.js` or provide an object hash which is loaded directly.  This
          "jquery": { "build": false },   // example skips building `jquery` and `underscore`.
          "underscore": { "build": false }
        }
      },
      "builderOptions":                   // (Optional) an object hash of any valid parameters for SystemJS Builder. This 
      {                                   // example sets `globalDeps` for associating `jquery` and `underscore` for UMD  
        "globalDeps":                     // and global bundles.
        {
          "jquery": "$",
          "underscore": "_"
        }
      }
    }
  ]
}

Please note that extraConfig can be a string or array of strings of filepaths relative to the project root path that defines an additional JSPM styled configuration file like config.js (wrapped in a System.config({ ... }); statement). This is particularly useful to define additional user supplied mapped paths that incorporate normalized JSPM package paths resolved from config.js. If an object literal / hash is supplied it is loaded directly.

Please note that builderOptions may include any valid optional parameters that SystemJS Builder supports.

For a comprehensive demo and tutorial see the backbone-es6-localstorage-todos repo which uses typhonjs-core-gulptasks.

typhonjs-core-gulptasks (c) 2015-present Michael Leahy, TyphonRT, Inc.

typhonjs-core-gulptasks may be freely distributed under the MPLv2.0 license.