grunt-niagara
v2.2.0
Published
Common Grunt tasks for Niagara modules
Downloads
1,433
Readme
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 globalnode_modules
directory is in yourNODE_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
, orsrcTest/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" ]
}
}
}