@jenkins-cd/js-builder

Jenkins JS Builder

JIRA

Table of Contents:

Overview
Features
Install
General Usage
Predefined Gulp Tasks
Redefining one of the predefined Gulp tasks
Bundling Options
Setting 'src' and 'test' (spec) paths
Command line options
Maven Integration
Sample Plugins (Jenkins - HPI)
JIRA

---

Overview

NPM utility for building CommonJS module bundles (and optionally making them js-modules compatible).

See js-modules.

The following diagram illustrates the basic flow (and components used) in the process of building a CommonJS module bundle. It uses a number of popular JavaScript and maven tools (CommonJS/node.js, Browserify, Gulp, frontend-maven-plugin and more).

The responsibilities of the components in the above diagram can be summarized as follows:

• CommonJS: JavaScript module system (i.e. the expected format of JavaScript modules). This module system works with the nice/clean synchronous require syntax synonymous with node.js (for module loading) e.g. var mathUtil = require('../util/mathUtil');. This allows us to tap into the huge NPM JavaScript ecosystem.
• Browserify: A build time utility (NPM package - executed as a Gulp "task") for "bundling" a graph of CommonJS style modules together, producing a single JavaScript file (bundle) that can be loaded (from a single request) in a browser. Browserify ensures that the require calls (see above) resolve properly to the correct module within the bundle.
• Gulp: A JavaScript build system (NPM package), analogous to what Maven is for Java i.e. executes "tasks" that eventually produce build artifacts. In this case, a JavaScript bundle is produced via Gulps execution of a Browserify "task".
• frontend-maven-plugin: A Maven plugin that allows us to hook a Gulp "build" into a maven build e.g. for a Jenkins plugin. See Maven Integration below.

Features

js-builder does a number of things:

1. Runs Jasmine tests/specs and produce a JUnit report that can be picked up by a top level Maven build.
2. Uses Browserify to produce a CommonJS module bundle file from a "main" CommonJS module (see the bundle task below). The bundle file is typically placed somewhere on the filesystem that allows a higher level Maven build to pick it up and include it in e.g. a Jenkins plugin HPI file (so it can be loaded by the browser at runtime).
3. Pre-process a LESS fileset to a .css file that can be picked up by the top level Maven build and included in the e.g. a Jenkins plugin HPI file. See the Bundling Options section below.

Install

npm install --save-dev @jenkins-cd/js-builder

This assumes you have node.js (minimum v4.0.0) installed on your local development environment.

Note this is only required if you intend developing js-modules compatible module bundles. Plugins using this should automatically handle all build aspects via maven (see later) i.e. simple building of a plugin should require no machine level setup.

General Usage

Add a gulpfile.js (see Gulp) in the same folder as the package.json. Then use js-builder as follows:

var builder = require('@jenkins-cd/js-builder');

builder.bundle('./src/main/js/myappbundle.js');

After running the the gulp command from the command line, you will see an output something like the following.

[17:16:33] Javascript bundle "myappbundle" will be available in Jenkins as adjunct "org.jenkins.ui.jsmodules.myappbundle".

Or if run from a maven project where the artifactId is (e.g.) jenkins-xyz-plugin.

[17:16:33] Javascript bundle "myappbundle" will be available in Jenkins as adjunct "org.jenkins.ui.jsmodules.jenkins_xyz_plugin.myappbundle".

From this, you can deduce that the easiest way of using this JavaScript bundle in Jenkins is via the <st:adjunct> jelly tag.

<st:adjunct includes="org.jenkins.ui.jsmodules.jenkins_xyz_plugin.myappbundle"/>

The best place to learn how to use this utility as part of building Jenkins plugins is to see the Sample Plugins repository.

Predefined Gulp Tasks

The following sections describe the available predefined Gulp tasks.

Note: If no task is specified (i.e. you just type gulp on its own), then the bundle and test tasks are auto-installed (i.e. auto-run) as the default tasks.

'bundle' Task

Run the 'bundle' task. See detail on this in the dedicated section titled "Bundling" (below).

gulp bundle

'test' Task

Run tests. The default location for tests is the spec folder. The file names need to match the pattern "*-spec.js". The default location can be overridden by calling builder.tests(<new-path>).

gulp test

See jenkins-js-test for more on testing. See command line options for --skipTest option. See command line options for --test option (for running a single test spec).

'bundle:watch' Task

Watch module source files (index.js, ./lib/**/*.js and ./lib/**/*.hbs) for change, auto-running the bundle task whenever changes are detected.

Note that this task will not be run by default, so you need to specify it explicitly on the gulp command in order to run it e.g.

gulp bundle:watch

'test:watch' Task

Watch module source files changes (including test code) and rerun the tests e.g.

gulp test:watch

'lint' Task

Run linting - ESLint or JSHint. ESlint is the default if no .eslintrc or .jshintrc file is found (using eslint-config-jenkins) in the working directory (.eslintrc is also searched for in parent directories).

gulp lint

See command line options for --skipLint, --continueOnLint and --fixLint options.

Redefining one of the predefined Gulp tasks

There are times when you need to break out and redefine one of the predefined gulp tasks (see previous section). To redefine a task, you simply call defineTask again e.g. to redefine the test task to use mocha:

builder.defineTask('test', function() {
    var mocha = require('gulp-mocha');
    var babel = require('babel-core/register');

    builder.gulp.src('src/test/js/*-spec.js')
        .pipe(mocha({
            compilers: {js: babel}
        })).on('error', function(e) {
            if (builder.isRetest()) {
                // ignore test failures if we are running test:watch.
                return;
            }
            throw e;
        });
});

Bundling Options

The following sections outline some options that can be specified on a bundle instance.

Bundling CSS and LESS

Note that bundling of CSS or LESS is also supported through a similar syntax e.g.

builder.bundle('src/main/css/bootstrap336/bootstrap.css');

Or via LESS:

builder.bundle('src/main/css/bootstrap336/bootstrap_tweaked.less');

The above commands will add all resources under src/main/css/bootstrap336 to the plugin classpath, making them available as adjuncts e.g. using the bundled bootstrap.css referenced above would be as simple as adding the following to the relevant .jelly file (check the build output for the correct adjunct):

<st:adjunct includes="org.jenkins.ui.jsmodules.bootstrap336.bootstrap"/>

Generating a bundle to a specific directory

By default, the bundle command will output the bundle to the target/classes/org/jenkins/ui/jsmodules, making the bundle loadable in Jenkins as an adjunct. See the General Usage section earlier in this document.

Outputting the generated bundle to somewhere else is just a matter of specifying it on the bundle instance via the inDir function e.g.

bundleSpec.inDir('<path-to-dir>');

Minify bundle JavaScript

This can be done by calling minify on js-builder:

bundleSpec.minify();

Or, by passing --minify on the command line. This will result in the minification of all generated bundles.

$ gulp --minify

onPreBundle listeners

There are times when you will need access to the underlying Browserify bundler just before the bundling process is executed (e.g. for adding transforms etc).

To do this, you call the onPreBundle function. This function takes a listener function as an argument. This listener function, when called, receives the bundle as this and the bundler as the only argument to the supplied listener.

var builder = require('@jenkins-cd/js-builder');

builder.onPreBundle(function(bundler) {
    var bundle = this;
    
    console.log('Adding the funky transform to bundler for bundle: ' + bundle.as);
    bundler.transform(myFunkyTransform);
});

Setting 'src' and 'test' (spec) paths

The default paths depend on whether or not running in a maven project.

For a maven project, the default source and test/spec paths are:

• src: ./src/main/js and ./src/main/less (used primarily by the bundle:watch task, watching these folders for source changes)
• test: ./src/test/js (used by the test task)

Otherwise, they are:

• src: ./js and ./less (used primarily by the bundle:watch task, watching these folders for source changes)
• test: ./spec (used by the test task)

Changing these defaults is done through the builder instance e.g.:

var builder = require('@jenkins-cd/js-builder');

builder.src('src/main/js');
builder.tests('src/test/js');

You can also specify an array of src folders e.g.

builder.src(['src/main/js', 'src/main/less']);

Command line options

A number of js-builder options can be specified on the command line. If you are looking for

--h (or --help)

Get a link to this documentation.

$ gulp --h

--minify

Passing --minify on the command line will result in the minification of all generated bundles.

$ gulp --minify

--test

Run a single test.

$ gulp --test configeditor

The above example would run test specs matching the **/configeditor*-spec.js pattern (in the test source directory).

Skip options: --skipTest, --skipLint, --skipBundle

Skip one or more of the tasks/phases e.g.

$ gulp --skipTest --skipLint

Lint options: --skipLint, --continueOnLint, --fixLint

Many of the more irritating formatting rule errors/warnings can be fixed automatically by running with the --fixLint option, making them a little less irritating e.g.

$ gulp --fixLint

Or if you are just running the lint task on it's own (explicitly):

$ gulp lint --fixLint

Alternatively, if you wish to run lint and see all of the lint errors, but not fail the build:

$ gulp --continueOnLint

And to skip linting completely:

$ gulp --skipLint

Maven Integration

Hooking a Gulp based build into a Maven build involves adding a few Maven <profile>s to the Maven project's pom.xml. For Jenkins plugins, the easiest way to get this integration is to simply have the plugin pom.xml depend on the Jenkins plugin-pom. For other project types, you'll need to copy those profiles locally (see plugin-pom).

These integrations hook the Gulp build into the maven build lifecycles. A few mvn build switches are supported, as described in the following sections.

-DcleanNode

Cleans out the local node and NPM artifacts and resource (including the node_modules folder).

$ mvn clean -DcleanNode

-DskipTests

This switch is a standard mvn switch and is honoured by the profiles defined in the plugin-pom.

$ mvn clean -DskipTests

-DskipTests also skips linting. See -DskipLint

-DskipLint

Skip linting.

$ mvn clean -DskipLint