NPM has become a hugely important part of the JavaScript ecosystem. It allows the easy packaging and publication of various projects and libraries, which can be based on JavaScript or other languages like for example TypeScript (or CoffeeScript).
At dizmo, we have developed the @dizmo/generator-module NPM module generator, which allows us to quickly create an NPM based library project with support for the following features:
-
Generation: the process of generating an NPM based module (based upon a template);
-
Transpilation: the process of translating from e.g. (modern) JavaScript or TypeScript to (older) JavaScript;
-
Bundling: the process of bundling various separate JavaScript modules into a single one;
-
Minification: the process of compressing a large module into a smaller one;
-
Linting: the process of checking that the coding style meets certain standards;
-
Testing: the process of testing code for expected behavior;
-
Coverage analysis: the process of checking how much of the code is covered by tests;
-
Continuous integration: the process of automatically running tests (on a remote server).
Generation
Our module generator is based on Yeoman. After installing Yeoman and the @dizmo/generator-module package, you can create an NPM project with:
yo @dizmo/module [--git] [--typescript|--coffeescript]
As you see we support pure JavaScript, TypeScript and CoffeeScript projects. Further – provided the git command is available – it is possible to initialized a project as a GIT repository. Let’s have a closer look at a JavaScript project:
JavaScript module
yo @dizmo/module --git
_-----_
| | ╭──────────────────────────╮
|--(o)--| │ Welcome to the awesome │
`---------´ │ dizmo module generator! │
( _´U`_ ) ╰──────────────────────────╯
/___A___\ /
| ~ |
__'.___.'__
´ ` |° ´ Y `
? Name your module: @dizmo/my-module
? Describe it: library module
? And your URL? https://github.com/hsk81
create package.json
create cli/run-build.js
create cli/run-lint.js
create cli/run-prepack.js
create cli/run-test.js
create cli/run-utils.js
create lib/index.js
create test/test.js
create LICENSE
create README.md
create .travis.yml
create .eslintrc.json
create .gitignore
create dist/.gitignore
create dist/.npmignore
Setting the project root at: /home/hsk81/my-module.git
Directory structure
tree my-module.git/ -a
my-module.git/
├── cli
│ ├── run-build.js
│ ├── run-lint.js
│ ├── run-prepack.js
│ ├── run-test.js
│ └── run-utils.js
├── dist
│ ├── .gitignore
│ └── .npmignore
├── .eslintrc.json
├── .gitignore
├── lib
│ └── index.js
├── LICENSE
├── package.json
├── README.md
├── test
│ └── test.js
├── .travis.yml
└── .yo-rc.json
4 directories, 16 files
where we have omitted above the .git sub-directory. Let’s have an even closer look at the various sub-directories:
./cli — the embedded build system
tree my-module.git/cli/ -a
my-module.git/cli/
├── run-build.js
├── run-lint.js
├── run-prepack.js
├── run-test.js
└── run-utils.js
0 directories, 5 files
These scripts beneath the ./cli folder provide support for all the features listed above: building (transpilation), linting (code standard adherence), testing (code correctness with coverage analysis), and prepackaging (bundling with minification).
The totality of this embedded build systems is less than 100 lines of code, and thanks to it being directly embedded into the project, it allows for specific adjustments of the build process.
./dist — the distribution folder
tree my-module.git/dist/ -a
my-module.git/dist/
├── .gitignore
└── .npmignore
0 directories, 2 files
The ./dist folder is the target location of the transpilation, bundling and minification processes. The .gitignore file here ensures that no bundle (which can be rather large) is committed to the GIT repository, while the (empty) .npmignore file ensures that the bundle is published to the NPM repository.
Hence, these two files should never be removed: Sometimes, it is necessary to clean-up the remaining files under ./dist, upon which great care should be taken to not also accidentally remove these .gitignore and .npmignore files.
./lib — the source folder
tree my-module.git/lib/ -a
my-module.git/lib/
└── index.js
0 directories, 1 file
The ./lib folder contains all the source files, which collectively make up the library; it is also possible to create sub-folders within it. By default a single index.js is given, which with its export statements provides the API of this library.
./test — the test folder
tree my-module.git/test/ -a
my-module.git/test/
└── test.js
0 directories, 1 file
The ./test folder contains test scripts (beginning with a test prefix), which together test the code under ./lib for expected behavior. By default a single test.js is given containing test cases for ./lib/index.js.
Development
Build
npm run build
without linting:
npm run -- build --no-lint
with UMD support (incl. minimization):
npm run -- build --prepack
with UMD support (excl. minimization):
npm run -- build --prepack --no-minify
By invoking npm run build all scripts under ./lib (and ./test) are by default transpiled and linted. Optionally, they are bundled and then minified. The transpilation is performed with Babel, linting with ESLint, (UMD) bundling with Browserify and minification with Terser.js.
Lint
npm run lint
with auto-fixing:
npm run -- lint --fix
By invoking npm run lint the linting process can also be triggered separately (outside of a build process), and it is performed with ESLint, whereas the .eslintrc.json file is used for configuring the set of linting rules.
Test
npm run test
without (re-)building:
npm run -- test --no-build
By invoking npm run test by default a build step is performed, after which the (transpiled) test scripts are executed – using the Mocha framework.
Cover
npm run cover
without (re-)building:
npm run -- cover --no-build
By invoking npm run cover by default a build step is performed, after which the (transpiled) test scripts are executed – using Mocha in combination with the Istanbul.js coverage framework (to provide corresponding statistics).
Publish
npm publish
initially (if public):
npm publish --access=public
By invoking npm publish the transpiled scripts under ./dist are prepackaged by bundling and minifying them, after which the bundle is then published to the NPM registry. While for bundling Browserify is used, for minification Terser.js is facilitated.
Continuous integration
$ cat .travis.yml
language : node_js
node_js :
- stable
install:
- npm install
script:
- npm run cover
after_script: "npx nyc report --reporter=text-lcov | npx coveralls"
When the source code of the NPM library is pushed to a GIT repository (for example on GitHub.com), it can automatically be tested using the Travis CI service. For this to work a .travis.yml configuration (as shown above) needs to be provided (which is generated by @dizmo/generator-module). Further, the Travis CI needs to have access to the corresponding GIT repository – to be able to pull and test the most recent commits.
Finally, the results of the tests is reported to the Coveralls service, which offers a user interface to interactively investigate the portions of the code base, which are (or are not) covered by the provided test cases (under ./test).
