Bentley npm Script Guidelines
This document is intended to provide suggestions for writing your own package's npm scripts for things such as building, running tests, and adding code coverage. The imodeljs-related repositories have moved away from gulp and gulp plugins to favor a more direct approach of running tasks. This allows us to depend directly on various npm packages instead of relying on gulp "middle-man" plugins that may not see the same update frequency as the npm packages themselves. For examples of npm scripts in use, please look at the imodeljs repository.
npm scripts are used by adding properties to the "scripts" object in a package's package.json file. These properties correspond to names that can be passed to the
npm run command to execute the properties' values as shell commands. For more information on creating and running scripts with npm, this article may be helpful to read.
The build-tools package includes a number of preconfigured node.js scripts to ease the development process. This includes scripts for testing, linting, and basic code coverage numbers. More information about these scripts can be found in the build-tools README.
With a properly configured tsconfig.json file, running the TypeScript compiler with
tsc should be enough for backend libraries and simple backend agents/services. For more information about tsconfig properties, see the TypeScript website. Frontend services or applications may require the use of Webpack or another more involved build solution.
Use rimraf as a cross-platform way to remove output folders (For example: rimraf ./lib). This package functions in a similar manner to the
rm -rf command in Unix shells.
cpx is a cross-platform copy utility for copying globs of files from a source to a destination directory. Useful for copying around files such as test files or assets.
Istanbul can be used together with mocha (in a ts-node configuration) to provide code coverage numbers and reports based on the package's test suite. This can be accomplished by running a ts-node test command directly with nyc (ex:
nyc run npm test:tsnode). Several types of reports are available, such as a summary of coverage in the console window or an html output that shows specifically which statements have been covered.
TSLint can be run separate from VS Code by using the package's CLI. This can be useful for verifying code before committing or for testing linting rules as part of a continuous integration process.
ts-node A typescript execution environment for code. Can be used to run Mocha tests and useful for generating code coverage percentages and reports.
tsconfig-paths - This may be necessary in multi-package repositories when dependencies are located using a folder's tsconfig "baseUrl" and "paths" attributes. This package is most often used with Mocha and ts-node to run tests directly from the TypeScript source files.
Last Updated: 08 January, 2020