This proposal introduces the idea of adding extracted package size information to the output summary fornpm install.

NOTE

This is an RFC. It is not a finalized, accepted feature request proposal. I've laid out the general process of implementation, but please don't make a PR implementing it until we've had time to discuss this.

Problem

Right now, there's no built-in way for npm users to figure out the size impact of adding or removing a package from their tree. In the past, it would have been easier because you could just trace the nested tree -- but now, because of flattening and deduplication, it's not trivial to take into account how many new packages would be added by a particular install, and what their total impact would be.

Changesnpm install

Thenpm install output will be changed such that total size information is included, and displayed in different ways depending on output mode:

npm install

The default, human-readable view currently looks like this:

➜ npm i webpack+ webpack@4.6.0added 536 packages from 24 contributors in 9.299s

It will be changed to display size information like this:

➜ npm i webpack+ webpack@4.6.0added 536 packages (+32MB) from 24 contributors in 9.299s

Or when the net value is negative:

➜ npm rm --dry-run pacoteremoved 39 packages (-5MB) in 5.148s

Even when both additions and removals have occurred:

➜ npm i --dry-run pacote@1+ pacote@1.0.0added 35 packages, removed 33 packages, updated 1 package and moved 1 package (-3MB) in 5.817s

npm install --json

The JSON format will add two things:size andunpackedSize field to each individualaction record, and asizeDelta field that totals up all theunpackedSize changes, in the toplevel:

➜ npm i ssri --dry-run --json{  "added": [    {      "action": "add",      "name": "ssri",      "version": "6.0.0",      "path": ".../node_modules/ssri",      "size": 12116,      "unpackedSize": 40772    }  ],  "removed": [],  "updated": [],  "moved": [],  "failed": [],  "warnings": [],  "sizeDelta": 40772, // positive or negative, depending on sum  "elapsed": 535}

npm install --parseable

The--parseable tab-delimited format will remain unchanged by default, to prevent potentially breaking parsers. Instead, the--long/-l option will be supported, which will add two additional columns next to each entry: the tarballsize, and theunpackedSize. It's up to users to add the numbers up themselves.

➜ npm i ssri --dry-run --parseable --longadd     ssri    6.0.0   node_modules/ssri 12116 40772

Implementation Details

This would need to patch both the npm installer (inlib/install.js andlib/install/actions/extract.js), as well as add an extra field to thefinalizeManifest process inpacote (lib/finalize-manifest.js).

npm installer changes

There are two changes to be made to the installer:

On the reporting side, update the three reporters (printInstalledForHuman,printInstalledForParseable, andprintInstalledForJSON) inlib/install.js. You should be able to check_size and_unpackedSize in thechild.package value, which holds the manifest for each installed package. Note: ifany of the packages in the calculation are missing the_unpackedSize value and the current reporter isprintInstalledForHuman, this file size summary should be omitted altogether. This case will happen for legacy registries when usingnpm install --dry-run -- it will otherwise be calculated from actual extracted size.

On the extract side, you will need to check if thechild.package._size andchild.package._unpackedSize properties exist. If they do not, you should set them based on metadata returned bypacote.extract().

pacote changes

pacote needs to do two things to support this:

• lib/finalize-manifest.js should be modified to get the compressed and uncompressed tarball size from package manifests,but only if they are available. They should be assigned to_size and_unpackedSize respectively, and are present in thedist.size anddist.unpackedSize properties of the manifest.

• extract.js andtarball.js should have their functions modified such that they return or emit size and unpackedSize as part of the metadata, where appropriate, after the operation has completed. This should be calculated from the actual data getting extracted (and may require changes tolib/extract-stream.js as well aslib/with-tarball-stream.js.