\n\n\n\n\n# Overview\n[NPM] utility for building [CommonJS] module [bundle]s (and optionally making them __[js-modules]__ compatible).\n\n> See __[js-modules]__.\n\nThe following diagram illustrates the basic flow (and components used) in the process of building a [CommonJS] module [bundle]. \nIt uses a number of popular JavaScript and maven tools ([CommonJS]/[node.js], [Browserify], [Gulp], [frontend-maven-plugin] and more).\n\n
\n \nThe responsibilities of the components in the above diagram can be summarized as follows:\n\n* __[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.\n* __[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].\n* __[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 [Gulp]s execution of a [Browserify] \"task\".\n* __[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.\n\n# Features\n`js-builder` does a number of things:\n\n1. Runs [Jasmine] tests/specs and produce a JUnit report that can be picked up by a top level Maven build.\n1. 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). \n1. 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.\n\n# Install\n\n```\nnpm install --save-dev @jenkins-cd/js-builder\n```\n\n> This assumes you have [node.js] (minimum v4.0.0) installed on your local development environment.\n\n> 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__.\n\n> Note you can also install `js-builder` globally and use it's CLI.\n\n# General Usage\n\nAdd a `gulpfile.js` (see [Gulp]) in the same folder as the `package.json`. Then use `js-builder` as follows:\n\n```javascript\nvar builder = require('@jenkins-cd/js-builder');\n\nbuilder.bundle('./src/main/js/myappbundle.js');\n\n```\n\nAfter running the the `gulp` command from the command line, you will see an output something like the following.\n \n```\n[17:16:33] Javascript bundle \"myappbundle\" will be available in Jenkins as adjunct \"org.jenkins.ui.jsmodules.myappbundle\".\n```\n\nOr if run from a maven project where the `artifactId` is (e.g.) `jenkins-xyz-plugin`.\n\n```\n[17:16:33] Javascript bundle \"myappbundle\" will be available in Jenkins as adjunct \"org.jenkins.ui.jsmodules.jenkins_xyz_plugin.myappbundle\".\n```\n\nFrom this, you can deduce that the easiest way of using this JavaScript bundle in Jenkins is via the `` jelly tag.\n\n```xml\n\n```\n\nThe best place to learn how to use this utility as part of building Jenkins plugins is to see the \n[Sample Plugins](https://github.com/jenkinsci/js-samples) repository.\n\n# Predefined Gulp Tasks\n\nThe following sections describe the available predefined [Gulp] tasks.\n\n> __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.\n\n## 'bundle' Task \nRun the 'bundle' task. See detail on this in the dedicated section titled \"Bundling\" (below). \n\n```\ngulp bundle\n```\n \n## 'test' Task\n\nRun tests. The default location for tests is the `spec` folder. The file names need to match the\npattern \"*-spec.js\". The default location can be overridden by calling `builder.tests()`.\n\n```\ngulp test\n```\n\n> See [jenkins-js-test] for more on testing.\n> See command line options for `--skipTest` option.\n> See command line options for `--test` option (for running a single test spec).\n\n## 'bundle:watch' Task\n\nWatch module source files (`index.js`, `./lib/**/*.js` and `./lib/**/*.hbs`) for change, auto-running the\n`bundle` task whenever changes are detected.\n\nNote that this task will not be run by default, so you need to specify it explicitly on the gulp command in\norder to run it e.g.\n\n```\ngulp bundle:watch\n```\n\n## 'test:watch' Task\n\nWatch module source files changes (including test code) and rerun the tests e.g.\n\n```\ngulp test:watch\n```\n\n## 'lint' Task\n\nRun linting - ESLint or JSHint. ESlint is the default if no `.eslintrc` or `.jshintrc` file is found \n(using [eslint-config-jenkins](https://www.npmjs.com/package/@jenkins-cd/eslint-config-jenkins)) in the working\ndirectory (`.eslintrc` is also searched for in parent directories).\n\n```\ngulp lint\n```\n\n> See command line options for `--skipLint`, `--continueOnLint` and `--fixLint` options.\n\n# Redefining one of the predefined Gulp tasks\n\nThere are times when you need to break out and redefine one of the predefined gulp tasks (see previous section).\nTo redefine a task, you simply call `defineTask` again e.g. to redefine the `test` task to use mocha:\n\n```javascript\nbuilder.defineTask('test', function() {\n var mocha = require('gulp-mocha');\n var babel = require('babel-core/register');\n\n builder.gulp.src('src/test/js/*-spec.js')\n .pipe(mocha({\n compilers: {js: babel}\n })).on('error', function(e) {\n if (builder.isRetest()) {\n // ignore test failures if we are running test:watch.\n return;\n }\n throw e;\n });\n});\n```\n\n# Bundling Options\n\nThe following sections outline some options that can be specified on a `bundle` instance.\n\n## Bundling CSS and LESS\n\nNote that bundling of __CSS__ or __LESS__ is also supported through a similar syntax e.g.\n\n```javascript\nbuilder.bundle('src/main/css/bootstrap336/bootstrap.css');\n```\n\nOr via [LESS]:\n\n```javascript\nbuilder.bundle('src/main/css/bootstrap336/bootstrap_tweaked.less');\n```\n\nThe above commands will add all resources under `src/main/css/bootstrap336` to the plugin classpath, making\nthem available as adjuncts e.g. using the bundled `bootstrap.css` referenced above would be as simple as\nadding the following to the relevant `.jelly` file (check the build output for the correct adjunct):\n\n```xml\n\n```\n\n## Generating a bundle to a specific directory\n\nBy default, the bundle command will output the bundle to the `target/classes/org/jenkins/ui/jsmodules`, making\nthe bundle loadable in Jenkins as an adjunct. See the General Usage section earlier\nin this document.\n\nOutputting the generated bundle to somewhere else is just a matter of specifying it on the `bundle` instance\nvia the `inDir` function e.g.\n\n```javascript\nbundleSpec.inDir('');\n```\n\n## Minify bundle JavaScript\n\nThis can be done by calling `minify` on `js-builder`:\n\n```javascript\nbundleSpec.minify();\n```\n\nOr, by passing `--minify` on the command line. This will result in the minification of all generated bundles.\n \n```sh\n$ gulp --minify\n```\n\n## onPreBundle listeners\n\nThere are times when you will need access to the underlying [Browserify] `bundler` just before the\nbundling process is executed (e.g. for adding transforms etc).\n\nTo do this, you call the `onPreBundle` function. This function takes a `listener` function as an argument.\nThis `listener` function, when called, receives the `bundle` as `this` and the `bundler` as the only argument to\nthe supplied `listener`.\n\n```javascript\nvar builder = require('@jenkins-cd/js-builder');\n\nbuilder.onPreBundle(function(bundler) {\n var bundle = this;\n \n console.log('Adding the funky transform to bundler for bundle: ' + bundle.as);\n bundler.transform(myFunkyTransform);\n});\n```\n\n# Setting 'src' and 'test' (spec) paths\nThe default paths depend on whether or not running in a maven project.\n\nFor a maven project, the default source and test/spec paths are:\n\n* __src__: `./src/main/js` and `./src/main/less` (used primarily by the `bundle:watch` task, watching these folders for source changes)\n* __test__: `./src/test/js` (used by the `test` task)\n\nOtherwise, they are:\n\n* __src__: `./js` and `./less` (used primarily by the `bundle:watch` task, watching these folders for source changes)\n* __test__: `./spec` (used by the `test` task)\n\n\n\nChanging these defaults is done through the `builder` instance e.g.:\n\n```javascript\nvar builder = require('@jenkins-cd/js-builder');\n\nbuilder.src('src/main/js');\nbuilder.tests('src/test/js');\n```\n\nYou can also specify an array of `src` folders e.g.\n\n```javascript\nbuilder.src(['src/main/js', 'src/main/less']);\n```\n\n# Command line options\n\nA number of `js-builder` options can be specified on the command line. If you are looking for\n\n\n## `--h` (or `--help`)\n\nGet a link to this documentation.\n \n```sh\n$ gulp --h\n```\n\n## `--minify`\n\nPassing `--minify` on the command line will result in the minification of all generated bundles.\n \n```sh\n$ gulp --minify\n```\n\n## `--test`\n\nRun a single test.\n \n```sh\n$ gulp --test configeditor\n```\n\nThe above example would run test specs matching the `**/configeditor*-spec.js` pattern (in the test source directory).\n\n## Skip options: `--skipTest`, `--skipLint`, `--skipBundle`\n\nSkip one or more of the tasks/phases e.g.\n \n```sh\n$ gulp --skipTest --skipLint\n```\n\n## Lint options: `--skipLint`, `--continueOnLint`, `--fixLint`\n\nMany of the more irritating formatting rule errors/warnings can be fixed automatically by running\nwith the `--fixLint` option, making them a little less irritating e.g.\n \n```sh\n$ gulp --fixLint\n```\n\nOr if you are just running the `lint` task on it's own (explicitly):\n \n```sh\n$ gulp lint --fixLint\n```\n\nAlternatively, if you wish to run `lint` and see all of the lint errors, but not fail the build:\n \n```sh\n$ gulp --continueOnLint\n```\n\nAnd to skip linting completely:\n \n```sh\n$ gulp --skipLint\n```\n\n# Maven Integration\nHooking a [Gulp] based build into a Maven build involves adding a few Maven ``s to the\nMaven project's `pom.xml`. For Jenkins plugins, the easiest way to get this integration is to simply\nhave the plugin `pom.xml` depend on the Jenkins [plugin-pom]. For other project types, you'll need\nto copy those profiles locally (see [plugin-pom]).\n\nThese integrations hook the [Gulp] build into the maven build lifecycles. A few `mvn` build\nswitches are supported, as described in the following sections.\n\n## `-DcleanNode`\n\nCleans out the local node and NPM artifacts and resource (including the `node_modules` folder).\n\n```\n$ mvn clean -DcleanNode\n```\n\n## `-DskipTests`\n\nThis switch is a standard `mvn` switch and is honoured by the profiles defined in the [plugin-pom].\n\n```\n$ mvn clean -DskipTests\n```\n\n`-DskipTests` also skips linting. See `-DskipLint`\n\n## `-DskipLint`\n\nSkip linting.\n\n```\n$ mvn clean -DskipLint\n```\n\n# CLI\n\nYou can install `js-builder` globally and then use it as command-line tool.\n\n```\nsudo npm install -g @jenkins-cd/js-builder \n```\n\nOnce installed, you do not need a globally installed [Gulp] in order to run `js-builder` builds. Instead, you can execute build tasks via\nthe `jjsbuilder` command (or aliases `jjsbuild` and `jjsb`).\n\nE.g. to run a full build, simply run `jjsbuilder` with no args (equivalent to running `gulp` with no args). \n\n```\njjsbuilder\n```\n\nTo run specific tasks e.g. `test` and `lint`.\n\n```\njjsbuilder --tasks test,lint\n```\n\nTo run specific tasks and specify a switch e.g. the `lint` task with the `--fixList` switch.\n\n```\njjsbuilder --tasks lint --fixLint\n```\n\nSo as you can see, the CLI operates more or less the same as when executing via `gulp`.\n\n# Without a `gulpfile.js`\n\nThe introduction of the CLI has allowed us to remove the `gulpfile.js` in a lot of situation\nbecause the CLI has it's own built in `gulpfile.js`.\n\nIf your `gulpfile.js` is as simple as:\n\n```javascript\nvar builder = require('@jenkins-cd/js-builder');\n\n//\n// Create a bundle.\n// See https://github.com/jenkinsci/js-builder\n//\nbuilder.bundle('src/main/js/rollbar.js');\n```\n\nThis `gulpfile.js` can be deleted and the bundling command moved to the `jenkinscd.bundle` section of the `package.json` e.g.\n\n```\n{\n\n \"jenkinscd\": {\n \"bundle\": [\n \"src/main/js/rollbar.js\"\n ]\n }\n}\n```\n\nThen you can add `scripts` to the `package.json` for executing build tasks. This allows the tasks to be executed without\ninstalling `js-builder` globally (which you would not want to require for e.g. a CI/CD build agent) e.g from a\n`package.json` generated by [`generator-blueocean-usain`](https://www.npmjs.com/package/generator-blueocean-usain).\n\n```\n{\n \n \"scripts\": {\n \"build\": \"jjsbuilder\",\n \"bundle\": \"jjsbuilder --tasks bundle\",\n \"test\": \"jjsbuilder --tasks test\",\n \"lint\": \"jjsbuilder --tasks lint\",\n \"lint:fix\": \"jjsbuilder --tasks lint --fixLint\",\n \"bundle:watch\": \"jjsbuilder --tasks bundle:watch\",\n \"mvnbuild\": \"jjsbuilder --tasks bundle\",\n \"mvntest\": \"jjsbuilder --tasks test,lint\"\n }\n}\n```\n\n# Managing bundle size\n\nGenerated JavaScript bundles can become very big very fast if you don't manage them properly. This is a constant\nchallenge and something you need to keep an eye on. We constantly do battle against this problem on [Blue Ocean].\n\nOnce it has been identified that a bundle has become very large, then you need to analyse the bundle to find out\nwhat modules/packages are causing the bloat and if there's an opportunity to [externalize] modules/packages that are\nin use across a number of bundles.\n \n> Note: [browserify-tree](https://www.npmjs.com/package/browserify-tree) is a tool that we developed to help analyse [Browserify] generated bundles.\n> Note: [disc] is another useful tool for analysing Browserify generated bundles. [See this Jenkins Dev list thread](https://groups.google.com/forum/?hl=en#!searchin/jenkinsci-dev/bundle$20size%7Csort:relevance/jenkinsci-dev/UknJzFso3y8/jbqwZINtBAAJ) for some details on how we've used it in the past.\n\n[bundle]: https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#what-is-the-difference-between-a-module-and-a-bundle\n[js-modules]: https://github.com/jenkinsci/js-modules\n[js-builder]: https://github.com/jenkinsci/js-builder\n[jenkins-js-test]: https://github.com/jenkinsci/js-test\n[NPM]: https://www.npmjs.com/\n[CommonJS]: http://www.commonjs.org/\n[node.js]: https://nodejs.org/en/\n[Browserify]: http://browserify.org/\n[Gulp]: http://gulpjs.com/\n[frontend-maven-plugin]: https://github.com/eirslett/frontend-maven-plugin\n[intra-bundle]: https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#what-does-module-loading-mean\n[inter-bundle]: https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#what-does-module-loading-mean\n[io.js]: https://iojs.org\n[Framework lib]: https://github.com/jenkinsci/js-libs\n[LESS]: http://lesscss.org/\n[Handlebars]: http://handlebarsjs.com/\n[Jasmine]: http://jasmine.github.io/\n[Moment.js]: http://momentjs.com/\n[plugin-pom]: https://github.com/jenkinsci/plugin-pom\n[externalize]: https://github.com/jenkinsci/js-samples/blob/master/step-04-externalize-libs/HOW-IT-WORKS.md#configure-node-build-to-externalize-dependencies\n[Blue Ocean]: https://github.com/jenkinsci/blueocean-plugin\n[disc]: https://github.com/hughsk/disc/\n","readmeFilename":"README.md"}
![\"Jenkins](\"res/build_workflow.png\")
\n \n