# Build infrastructure

The build infrastructure consists of a few tools made available through npm run commands.

This document is concerned with building the JavaScript source code. See Documentation Infrastructure for how the documentation and website are generated.

# Building

# build everything
npm run build

# remove everything in dist
npm run clean

npm run build first runs build:pre to setup the dist directory, overwriting src/version.js to expose the package version:

dist
└── src
    └── <ES6 files>

npm run build then runs build:umd, build:amd, build:common, build:esm and creates the following structure in the dist directory:

dist
├── <UMD bundle>
├── amd
│   └── <UMD module files>
└── common
│   └── <CommonJS module files>
└── esm
│   └── <ES6 module files compiled to ES5>
└── src
    └── <ES6 module files>

npm run build then runs build:post after the bundle and modules have been created, mutating the the dist directory to the following structure (that is published to npm):

dist
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE.txt
├── <UMD bundle>
├── <CommonJS module files>
├── amd
│   └── <UMD module files>
└── esm
│   └── <ES6 module files compiled to ES5>
└── src
    └── <ES6 module files>

At the end npm run build also runs build:archive, which creates a ZIP archive of dist and saves it to dist/ally.js.zip.

# Building the UMD bundle

ally.js is made available in one convenient file, consumable as a browser global (window.ally), via AMD and CommonJS (exposed in UMD). The source is compiled to the distributable by browserify using babelify and rollupify to resolve the ES6 modules.

# build the UMD bundle
npm run build:umd

# remove everything in dist
npm run clean

# Building AMD and CommonJS and ES6 modules

To allow developers to use selected features (rather than import everything), the ES6 source (src) is made available in ES5 via AMD and CommonJS in dist/amd and dist/common and as ES6 modules in dist/esm.

# convert to CommonJS modules
npm run build:common

# convert to AMD modules
npm run build:amd

# keep converting to dist/amd while working on src
npm run watch:amd

# convert to compiled ES6 modules
npm run build:esm

Since v1.4.0 the AMD modules are actually UMD modules, because of how babel 6 handles default exports. Since UMD can be consumed by both AMD and CommonJS system, a separate CommonJS build is not necessary anymore. However, changing the npm module's structure is a breaking change and has thus been deferred to the next major release.

# Linting

We use eslint with eslint-config-semistandard and a few custom rules to keep the JavaScript sane. The markdown files are kept sane through markdownlint and eslint-plugin-markdown.

# Usage

# lint everything
npm run lint

# lint only JavaScript
npm run lint:js

# lint only Markdown
npm run lint:md

# lint only JavaScript in Markdown
npm run lint:md:js

# fix linting errors
npm run lint:js:fix

Linting is done automatically during git commit by way of pre-commit and limited to the actually changed files by way of lint-staged in order to keep git commit as fast as possible.