scripts/README.md.in
# @masnagam/npm-diet
> A tool to help keeping your package slim
[](https://badge.fury.io/js/%40masnagam%2Fnpm-diet)
[](https://travis-ci.org/masnagam/npm-diet)
[](https://ci.appveyor.com/project/masnagam/npm-diet/branch/master)
[](https://www.codacy.com/app/masnagam/npm-diet?utm_source=github.com&utm_medium=referral&utm_content=masnagam/npm-diet&utm_campaign=Badge_Grade)
[](https://codeclimate.com/github/masnagam/npm-diet/maintainability)
[](https://codeclimate.com/github/masnagam/npm-diet/test_coverage)
`npm-diet` is a CLI tool comprised of several commands which can be used for
analyzing the total size of NPM packages installed.
`npm-diet` can not be used for analyzing the size of a web application bundle.
Try to use the following tools for such purpose.
* [package-size](https://www.npmjs.com/package/package-size)
* [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer)
* [bundlephobia.com](https://bundlephobia.com/)
* You can search other tools using `npm search`...
## Installation
```console
$ npm install -g @masnagam/npm-diet
```
## How does this work?
Very simple:
1. Install specified packages using `npm install`
2. Correct installed packages using `npm ls --parseable`
3. Traverse directories in each package, and compute the sum of file sizes
See [lib/analyze/measure.js](./lib/analyze/measure.js).
## Limitations
There are some limitations at this moment:
* `npm-diet measure` does not take account of sizes of directories
* `npm-diet measure` does not compute actual sizes on disk
## Typical usages
Show a brief summary of an analysis:
```console
$ npm-diet measure del | npm-diet summary
@@npm-diet measure del | npm-diet summary
```
Show details of duplicates:
```console
$ npm-diet measure del | npm-diet show dup --package-path
@@npm-diet measure del | npm-diet show dup --package-path
```
Show the top 3 packages in descending order of size:
```console
$ npm-diet measure livereload | npm-diet show measure --top=3
@@npm-diet measure livereload | npm-diet show measure --top=3
```
Specify multiple packages:
```console
$ npm-diet measure mocha chai sinon | npm-diet summary
@@npm-diet measure mocha chai sinon | npm-diet summary
```
Process the analysis result with [jq]:
```console
$ npm-diet measure commander | jq '.packages[].files[] | .path, .size'
@@npm-diet measure commander | jq '.packages[].files[] | .path, .size'
```
Use a `package.json` file for analysis:
```console
$ cat package.json
{
...
"dependencies": {
"npm-run-all": "^4.1.3",
"rimraf": "^2.6.2"
}
}
$ npm-diet pkg-deps package.json | npm-diet measure --stdin | \
npm-diet summary
@@echo '["npm-run-all@^4.1.3","rimraf@^2.6.2"]' | npm-diet measure --stdin | npm-diet summary
```
Replace `rimraf` with `del`:
```console
$ echo '["npm-run-all","rimraf"]' | \
npm-diet measure --stdin _rimraf del | npm-diet summary
@@echo '["npm-run-all","rimraf"]' | npm-diet measure --stdin _rimraf del | npm-diet summary
```
Show delta values between two package sets:
```console
$ (npm-diet measure chalk ; npm-diet measure colors) | \
npm-diet delta --stdin | npm-diet summary
@@(npm-diet measure chalk ; npm-diet measure colors) | npm-diet delta --stdin | npm-diet summary
```
Show details of a delta analysis:
```console
$ (npm-diet measure mini-lr ; npm-diet measure tiny-lr) | \
npm-diet delta --stdin | npm-diet show delta --top=3
@@(npm-diet measure mini-lr ; npm-diet measure tiny-lr) | npm-diet delta --stdin | npm-diet show delta --top=3
```
## Data Models
The following data structures are still under consideration. They may be
changed in the near future.
### Measure Analysis
```js
{
"type": "measure",
"specs": [ ... ], // list of package specifiers
"numPkgs": 1, // the number of packages
"size": 61750, // sum of package sizes
"numFiles": 6, // sum of the numbers of files
"packages": [ ... ] // list of packages
}
```
### Delta Analysis
```js
{
"type": "delta",
"baseline": { ... }, // analysis of the baseline package set
"subject": { ... }, // analysis of the subject package set
"delta": { ... }, // delta values (metrics withtout `packages`)
"increase": { ... }, // metrics of added packages
"decrease": { ... }, // metrics of removed packages
"common": { ... } // metrics of common packages
}
```
### Duplicate Analysis
```js
{
"type": "duplicate",
"specs": [ ... ], // list of package specifiers
"numPkgs": 2, // the number of duplicate packages
"size": 14955, // sum of duplicate sizes
"numFiles": 8, // sum of the numbers of files
"duplicates": [ ... ] // list of duplicates
}
```
### Package Specifier
```js
{
"name": "@masnagam/npm-diet", // package name
"detail": "*" // semver, url or local path
}
```
### Metrics
Subsequent analysers may add other metrics.
```js
{
"numPkgs": 1, // the number of packages
"size": 61750, // sum of package sizes
"numFiles": 6, // sum of the numbers of files
"packages": [ ... ] // list of packages
}
```
### Duplicate
```js
{
"name": "pify", // name
"size": 14955, // sum of duplicate sizes
"numFiles": 8, // sum of the number of files
"packages": [ ... ] // list of packages
}
```
### Package
```js
{
"name": "commander", // name
"version": "2.16.2", // version
"size": 61750, // sum of file sizes
"files": [ ... ], // list of files
"path": "node_modules/commander" // relative path to the package
}
```
### File
```js
{
"path": "CHANGELOG.md", // relative path from the package dir
"size": 10068 // file size in bytes
}
```
## Great predecessors
* [cost-of-modules] - Find out which of your dependencies is slowing you down
* [package-size-analyzer] - Package Size Analyzer when using npm package
## License
This software is distributed under the Apache license 2.0. See
[LICENSE](./LICENSE) file for details.
[jq]: https://stedolan.github.io/jq/
[cost-of-modules]: https://github.com/siddharthkp/cost-of-modules
[package-size-analyzer]: https://www.npmjs.com/package/package-size-analyzer