grunt-niagara v2.2.0

grunt-niagara

Common Grunt tasks for Niagara modules

Getting Started

This plugin requires Grunt ~1.0.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

npm install grunt-niagara --save-dev

grunt.loadNpmTasks('grunt-niagara');

If you are creating a brand new Niagara web module, consider using grunt-init-niagara to get up and running quickly.

Using grunt-niagara

grunt-niagara provides no custom tasks of its own. Instead, it loads other tasks and smart default configurations for those tasks into your project. To see these tasks, after following the steps above, type grunt usage.

A bare minimum config

Most of the tasks provided require Grunt configurations of their own. grunt-niagara will provide default configurations that reflect Niagara recommended practices, so the required configuration is kept to a minimum and you can get on with developing!

Almost all the tasks only require a src property with the files needed. These can easily be shared among the different tasks.

If you don't wish to use a certain task, just leave its configuration object out of the grunt config and grunt-niagara will disable it.

Additional options provided will override the defaults, so your own configuration can be as specific as you need. This is just a minimum to get started.

var SRC_FILES = [
      'src/rc/**/*.js',
      '!src/rc/**/*.min.js'
    ],
    TEST_FILES = [
      'srcTest/rc/**/*.js'
    ],
    ALL_FILES = SRC_FILES.concat(TEST_FILES);

module.exports = function runGrunt(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),

    jsdoc:     { src: SRC_FILES },
    eslint:    { src: ALL_FILES },
    watch:     { src: ALL_FILES },
    karma:     {},
    babel:     {},
    requirejs: {},
    niagara:   {
      station: {
        forceCopy: true,
        sourceStationFolder: './srcTest/stations/bajauxUnitTest'
      }
    }
  });

  grunt.loadNpmTasks('grunt-niagara');
};

Notes about default behavior

jsdoc

Generates JSDocs and places them in jsdoc-dir.

Minimal config:

src: array of file definitions to process for JSDoc

eslint

Performs ESLint analysis and fails the build if any errors are found. Error report will be placed in eslint-reports-dir.

Tip: If running ESLint direct from the command line, type eslint:src to get output formatted for display. Type eslint:fix to automatically fix all fixable errors.

Minimal config:

src: array of file definitions to analyze with ESLint.

karma

Runs browser-based unit tests. Its default starting point will be to execute JS found at srcTest/rc/browserMain.js. Test reports will be placed in junit-reports-dir, and code coverage reports (if running grunt ci) will be placed in coverage-reports-dir.

If niagara.station config is present, it will start a station prior to running tests.

As of grunt-niagara version 2, the default browser for running tests is ChromeHeadless. If Chrome cannot be found when running tests, do one of the following:

• Add a CHROME_BIN environment variable pointing to a valid chrome.exe
• Install puppeteer globally (e.g. npm install -g puppeteer), and ensure that the global node_modules directory is in your NODE_PATH environment variable.

Minimal config:

No configuration necessary. An empty object will enable Karma tests.

babel

As of grunt-niagara 2.0, Babel transpilation is provided out of the box. This will enable you to use ES6 syntax features in your code and have them transpiled down to ES5 for browser compatibility.

If enabled, by default, all JS files in src/rc and srcTest/rc will be transpiled into the build directory for packaging into the final JAR. In conjunction, Karma will look in build/karma to run tests against the transpiled files. (If using grunt-init-niagara, check your paths config in browserMain.js to ensure RequireJS is looking in build/karma.)

The transpilation can be configured using the sourceMappings property as described below.

Minimal config:

No configuration necessary. An empty object will enable the default transpilation behavior.

copy

You may want certain files to be copied directly into the JAR without any sort of linting or testing, such as third-party libraries you did not create. The default behavior is to simply copy over any non-JS files in src/rc and srcTest/rc, and any files at all in src/ext and srcTest/ext. Remember to include these ext directories in your Gradle file if needed.

Minimal config:

No configuration necessary - will always be available.

niagara.station

Configures a station to start up for Karma tests. See the niagara-station npm module.

pkg

Reads the contents of package.json. This is required for grunt-niagara to function.

requirejs

Performs r.js optimization. By default, it will include every .js file under src/rc and place the optimized file at build/src/rc/{moduleName}.built.min.js.

It will map nmodule/yourModuleName to the src directory. This conforms to the Niagara RequireJS module ID convention, where nmodule maps to a URL starting with /module. Therefore a file at src/rc/foo.js should map to the RequireJS ID nmodule/yourModuleName/rc/foo.

RequireJS plugins baja!, css!, log!, and lex! will be disabled during the build, as they only make sense in the context of a running station. To configure this list, set your disablePlugins option to an array of plugin names (omitting the '!'). Other common Niagara modules like bajaux and Promise will be excluded using the empty: syntax. Handlebars templates will be compiled using the copy of Handlebars from the js module jar.

One build task named src will be present, so you can override default behavior like this:

require: {
  src: {
    options: {
      include: [ 'nmodule/myModule/rc/OnlyThisOneModule' ],
      out: 'build/src/rc/differentTargetFile.built.min.js'
    }
  },
  anotherBuild: {
    options: { /* ... */ }
  }
}

Or, if you wish to "cancel out" the src build and configure all your builds by hand, just set it to a falsy value:

require: {
  src: false,
  myOwnBuild: {
    options: { /* ... */ }
  }
}

Minimal config:

No configuration necessary. An empty object will allow r.js optimization as described.

watch

Starts up in watch mode, performing ESLint analysis and running Karma tests every time you save a file.

If you want to customize which Grunt tasks are run when you save a file, pass a function as a tasks parameter like this:

watch: {
  src: SRC_FILES,
  tasks: function (defaultTasks) {
    // the default tasks run ESLint followed by Karma.
    return [ 'run-first' ].concat(defaultTasks).concat([ 'run-after' ]);
  }
}

As of grunt-niagara 2.0, the watch task will be configured to run linting and transpilation only on those files which were actually changed, which will help speed up development. To disable this behavior so all files are linted and transpiled on every change, set the onDemand option to false:

watch: {
  options: { onDemand: false },
  src: SRC_FILES
}

By default, Babel will perform one full run when starting up watch mode. This will ensure that all files are correctly transpiled (otherwise files that were changed while watch was not running, such as when pulling from source control, would be missed). To skip this initial Babel run, pass the option --quick-start=true.

Minimal config:

src: array of file definitions that will trigger a test run when saved.

sourceMappings

grunt-niagara provides transpilation and RequireJS optimization out of the box. These functions also make some assumptions about the structure of your module (the same structure we use at Tridium):

• All JS to be transpiled lives in src/rc
• All CSS, HTML, images, etc. to be used as-is also live in src/rc
• All test code lives in srcTest/rc
• All external dependencies live in src/ext, or srcTest/ext for test-only dependencies - these are to be used without modification

But you may wish to retrofit grunt-niagara to an existing module, and you may not want to move all your files around to conform to these conventions. You can point grunt-niagara at different directories using the sourceMappings config. You can build this by hand, but the gruntSources module includes some APIs that will make this much easier.

Please note that customization is not unlimited - all transpilation must target build/src or build/srcTest or their subdirectories.

An example is below:

const { allFiles, allJsFiles, allFilesWithoutExtensions } = require('grunt-niagara/lib/gruntSources');

///...
sourceMappings: {
  // say my ES6 code lives in src/es6, not src/rc...
  source: allJsFiles().from('src/es6').to('build/src/es6'),

  // ...and my css and images aren't in src/rc, they're in src/com/mycompany instead...
  resources: allFilesWithoutExtensions([ 'js', 'java' ]).from('src/com/mycompany').to('build/src/com/mycompany'),

  // ... and i put my third party dependencies in src/lib instead of src/ext.
  ext: allFiles().from('src/lib').to('build/src/lib')

  // the corresponding test properties are test, testResources, and testExt
}

Global Options

If you would like to customize the default values for command-line options, you can do so using an options configuration file by using the options command-line argument.

grunt <task> --options="optionsFile.json"

The default value is <niagara_user_home>/etc/my-grunt-options.json, so you can place a JSON file in this location and it will always be used. In order to override something such as station-log-level, you could use a JSON file like this:

{
  "station-log-level": "INFO"
}

Global Config

As with options, you can also override Grunt configuration globally using the config command-line argument.

grunt <task> --config="configFile.json"

The default value is <niagara_user_home>/etc/my-grunt-config.json. The JSON will be merged in with the Grunt config before running any tasks, so you can add any configuration you like. In order to override something such as adding a custom Karma launcher, you would use a JSON file like this:

{
  "karma": {
    "options": {
      "customLaunchers": {
        "MyCustomLauncher": {
          "base": "ChromeHeadless",
          "displayName": "My Custom Launcher"
        }
      }
    },
    "ci": {
      "browsers": [ "MyCustomLauncher" ]
    }
  }
}