@bloomreach/frontend-build

READ FIRST

This package, although published as a public package, is only meant to be used internally at Bloomreach. We offer no support whatsoever to anyone outside Bloomreach.

Frontend Build

Frontend build system for frontend apps at Bloomreach. Features:

• Linting, compiling and optimizing of ES2015+ files
• Linting, compiling and optimizing of Typescript files
• Specific support for Angularjs and Angular apps.
• Run unit tests using the Karma Test Runner and Jasmine framework
• Provide text-summary and html coverage reports over original source code
• Linting, compiling and optimizing of Sass (scss) files
• Loading of html, svg, images and fonts
• Provide sourcemaps to original source code

Changelog

Release notes are found in the changelog.

Frontend Build release steps

We use release-it to release to @bloomreach. A config file is included with preset configuration options.

Examples of commands:

• Release new minor version: npm run release-it -- --increment=minor --src.commitMessage="[Relevant JIRA issue] Release %s"
• Release new pre-release under a npm tag: npm run release-it -- --increment=prerelease --src.commitMessage="[Relevant JIRA issue] Release %s" --prereleaseId="[relevant prerelease] --npm.tag=["relevant npm tag"]"
• Non-interactive mode patch version publish: npm run release-it -- --non-interactive --src.commitMessage="[Relevant JIRA issue] Release %s"

Webpack build options

You can use the following options as follows: npm run build -- --<option1> --<option2>

• analyze: show bundle content as convenient interactive zoomable treemap webpack-bundle-analyzer
• cache: enable module caching with the HardSourceWebpackPlugin
• dll: run Webpack (currently only for tests) with the DLL plugin enabled, note that you need to generate your DLL's prior to this by executing npm run buildDll
• lint: run eslint, tslint and sasslint on your code
• profile: adds timing information to the --verbose output, see https://webpack.js.org/api/cli/#profiling for more information
• transpileOnly: skip TypeScript type checking, by default it will run in a forked process
• verbose: get detailed build output information

Webpack DLL's

To improve the build speed for tests, we provide the possibility to use the Webpack DLL plugin. In short, this will ensure only our own sources are packaged, and external modules (like angular) will simply be included from node_modules.

To use the DLL setup, we first need to generate the DLL manifest(s): npm run buildDll This will generate a manifest JSON file with a related bundle javascript file. Now you can run the tests with DLL's: npm run test -- --dll

Note: by default, all dependencies in your package.json file are bundled into a single DLL. To have more finegrained control (change order, exclude modules, etc) you can specify a dlls property in your build.conf.js file, e.g.

dlls: {
    angularjs: [
      'angular',
      'angular-animate',
    ],
    angular: [
      'core-js',
      'hammerjs',
      'es6-shim'
    ]

Webpack special loader rules

• SVGs located in images/html/ are loaded as strings so they can be used inline
• Sass files in styles/string are loaded as strings so they can be used inline
• Sass files for Angular apps following the convention *.component.scss will be loaded as strings so they can be used inline

Linting with Codelyzer

The frontend-build tslint.json includes rules provided by Codelyzer because we copied the tslint config from @angular/cli. However we do not want to dictate the @angular/core version from frontend-build (@angular/core is a peerDependency of Codelyzer) so we leave it up to the end project to depend on and implement codelyzer and its config in tslint.

Testing

Loading HTML, CSS and JSON fixtures

The default Karma setup of frontend-build exposes the jasmine-jquery module for handling HTML, CSS and JSON fixtures, as well as provide a set of custom matchers that simplify validating DOM conditions, e.g. expect($('#id-name')[0]).toBeInDOM().

Fixture files should be defined adjacent to the spec files that use them, or at least as close as possible. They follow the same naming convention as the spec files and are named with a .fixture suffix, e.g. cms.login.fixture.html or cms.config.fixture.json. Karma can be instructed to serve fixture files over it's HTTP-server by adding a file pattern to the files array in the project's karma.conf.js. The default pattern is saved in cfg.src.fixtures and matches { pattern: cfg.srcDir + '**/*.fixture.+(js|html|css|json)', included: false}.

Frontend-build instructs Karma by default to proxy the path /spec/javascripts/fixtures/ (which is the default fixtures path of jasmine-jquery) to /base/src/app/. This is a combination of Karma's base path for serving files over HTTP and the root folder where frontend-build expects your Angular code to live.

When changing the karma options you can customize the proxy path with the following options:

• override cfg.srcDir in your build.conf.js which changes the default proxy path from /base/src/app to /base/[your src dir]/app
• override cfg.karmaFixtureProxyPath in your build.conf.js directly
• override options.proxies in your karma.conf.js, then you will have to replicate these two configuration values:

proxies: {
  '/spec/javascripts/fixtures/': '[your proxy path]',
  '/spec/javascripts/fixtures/json/': '[your proxy path]',
},

Example project setup and code

|- src
  |- app
    |- main.js
    |- main.spec.js
    |- main.fixture.html
    |- main.fixture.json
    |- dialogs
      |- dialog.fixture.html
      |- dialog.fixture.css
      ..

In main.spec.js you can then load your fixtures with:

// Load html fixture into the DOM
jasmine.getFixtures().load('main.fixture.html');
// from a subfolder
jasmine.getFixtures().load('dialogs/dialog.fixture.html');

// load css fixture into the DOM
jasmine.getStyleFixtures().load('dialogs/dialog.fixture.css');

// Load JSON fixture object
var jsonObject = jasmine.getJSONFixtures().load('main.fixture.json');

For more control over the paths you can use the following snippet in your spec files:

beforeEach(function () {
  jasmine.getFixtures().fixturesPath = 'base/spec/js/fixtures';
  jasmine.getStyleFixtures().fixturesPath = 'base/spec/css/fixtures';
  jasmine.getJSONFixtures().fixturesPath = 'base/spec/json/fixtures';
});