util.pkgwrap

A script wrapper for package.json scripts.

This creates a command line program named pkgwrap in node_modules/.bin. It is used to wrap common/reusable command line operations for launching scripts in NPM or Yarn script. The wrapper simplifies the setting of command line parameters for the programs below to create a set of opinionated options. e.g. dynamically setting the temporary directory for nyc output or parallel building of JSX files or setting the default list of file extensions used by prettier.

This implementation is opinionated and wraps the following packages:

• build: typescript (tsc) and babel (if --jsx used)
• clean: rimraf
• coverage: coveralls
• docs: jsdoc-to-markdown and JSDoc
• lint: tslint
• style: prettier
• reporting: nyc
• testing: mocha or ava (if --ava used) or jest (if --jest used). Most of the projects that use this module use ava for testing.

Installation

To install as an application dependency with cli:

$ npm install --save util.pkgwrap

This module must be a regular dependency in a project and NOT a development one. A package that uses the pkgwrap script must have it installed in the node_modules/.bin when installed by other packages. If it is not, then the pkgwrap calls for postinstall will fail to find it when your package is installed as a 3rd party dependency.

Usage

This is a command line package used with the scripts section of package.json. An example would be:

"scripts": {
    "build": "pkgwrap --build --jsx",
    "clean": "pkgwrap --clean",
    "coverage": "pkgwrap --coverage",
    "docs": "pkgwrap --docs --site",
    "lint": "pkgwrap --lint",
    "postinstall": "pkgwrap --postinstall",
    "prettier": "pkgwrap --prettier",
    "report": "pkgwrap --reporting",
    "test": "pkgwrap --testing --ava"
}

Commands

• --build: calls the typescript build process
• --clean: removes intermediate build/distribution files from the module. This includes dist, build, coverage.
• --coverage: runs coveralls to upload report details after a successful build.
• --docs: generates markdown and website documents for a module
• --globals: takes global dependencies from package.json ("globalDependencies") and installs them. These follow the same conventions as dependencies/devDependencies.
• --lint: calls the tslint code checking program
• --postinstall: this is executed after npm install. It is used to create directories or fix their permissions (for programs like nyc or coverage).
• --prettier: calls the prettier style formatter program to ensure all source files conform to an opinionated format.
• --reporting: runs nyc to create information that can be used in reporting testing coverage
• --testing: calls the testing program. It uses mocha by default. It can be overriden to use ava with an additonal --ava flag or --jest.

Options

• --ava: Used with the --testing command to use the ava test runner.
• --debug: Turns on verbose output where available.
• --jest: Used witht he --testing command to use the jest test runner.
• --jsx: Used with the --build command to search for .jsx files and use babel to transpile them.
• --minWorkers (5): Used with --build to set the smallest number of workers in the execution pool for building JSX files with babel (builds JSX files in parallel)
• --maxWorkers (10): Used with --build to set the largest number of workers in the execution pool for building JSX files with babel (builds JSX files in parallel)
• --site: Used with the --docs command to generate a corresponding jsdoc website (jsdoc)
• --webpack: Used with the --build command to invoke webpack if it is avaialble (or will generate an error if it is not)

Dependencies

The following development dependencies must be included within the package.json file of the project that uses this cli:

• ava
• babel
• coveralls
• intelli-espower-loader (if using mocha)
• jest
• jsdoc
• jsdoc-to-markdown
• mocha
• nyc
• powerassert (if using mocha)
• prettier
• rimraf
• typescript
• tslint