Pragmatist

A collection of tasks to standardize builds.

Tasks

Tasks that are not documented (including dependencies of the documented tasks that are not documented) are considered private and can be changed/renamed or removed without a warning.

`lint`

Uses Canonical to lint all *.css, *.scss and *.js files in ./src and ./tests directories.

`format-css`

Uses csscomb to format all *css and *.scss files in ./src directory in accordance with Canonical requirements.

`build`

Copies all files from ./src directory to ./dist.
Uses Babel to compile files in ./src directory.
- Compiled files overwrite the existing files in ./dist directory.
- Source Maps are stored in the ./dist directory`.
- Uses babel-plugin-lodash.
- Babel compiler is configured to use stage 0 ES features.

`test`

Uses Babel to compile files in ./tests directory.
Uses Istanbul to generate test coverage.
Uses Mocha to execute tests in ./tests directory.

Istanbul assumes that tests are using ./src files (as opposed to ./dist).

Istanbul coverage report is written to the ./coverage directory. A coverage summary is included in the CLI output.

`watch`

Runs lint, test and build tasks every time ./src/**/*.js or ./tests/**/*.js changes.

`watch-lint`

Runs lint task every time ./src/**/*.js or ./tests/**/*.js changes.

`watch-test`

Runs test task every time ./src/**/*.js or ./tests/**/*.js changes.

`watch-build`

Runs build task every time ./src/**/*.js or ./tests/**/*.js changes.

Gulp Tasks

pragmatist can be used to extend your existing gulp tasks.

import gulp from 'gulp';
import pragmatist from 'pragmatist';

/**
 * @param {Object} gulp
 * @param {string} prefix Used to prefix all pragmatist tasks.
 * @returns {undefined}
 */
pragmatist(gulp);

This will make all pragmatist tasks available under pragmatist: namespace, e.g.

gulp pragmatist:test

CLI Program

pragmatist can be used as a CLI program to run all the tasks.

npm install pragmatist -g

Tasks can be executed by running:

pragmatist <task>

Just running pragmatist will execute the test task.

Multiple tasks can be executed one after the other, e.g.

pragmatist <task #1> <task #2> <task #3>

ES5

The default behavior for build task is to compile code for node. Specifically, for the latest version of node.

To compile code down to ES5, you must add --es5 flag to the command line, e.g.

pragmatist build --es5

Notifications

Use --notifications flag to enable OS level notifications about errors that occur during the build.

pragmatist build --notifications

Types

Use --type-assertions flag to enable runtime type assertions.

pragmatist build --type-assertions

NPM

A typical project using pragmatist will define the following NPM scripts:

"scripts": {
   "pragmatist": "pragmatist",
   "lint": "npm run pragmatist lint",
   "test": "npm run pragmatist test",
   "build": "npm run pragmatist build",
   "watch": "npm run pragmatist watch",
   "watch-lint": "npm run pragmatist watch-lint",
   "watch-test": "npm run pragmatist watch-test",
   "watch-build": "npm run pragmatist watch-build"
},

Ignore Unnecessary Files

This is just a reminder. Pragmatist will produce several files that you do not want to commit to the repository or include in the npm bundle.

Add to .gitignore:

node_modules
coverage
dist
*.log
.*
!.gitignore
!.npmignore
!.babelrc
!.travis.yml

Add to .npmignore

src
tests
coverage
.*
*.log

bitspook / pragmatist