mweststrate / import-size

Measure the real, minified, tree-shaken impact of individual imports into your app

import-size

Measure the real, minified, tree-shaken impact of individual imports into your app

Usage

npx import-size <dependency> <imports>. For example:

npx import-size immer produce enablePatches

npx import-size --report immer produce enableES5 enablePatches enableMapSet

If you want to generate reports as part of your tooling, you might want to import-size as development dependency using yarn or npm.

Why

This tool is basically the result of a long-winded twitter thread. A long story short: this tool will calculate how many bytes a dependency costs, after bundling it for production and apply-ing treeshaking, based on the things you actually want to import.

import-size fixes that and comes as a convenient CLI tool. It wraps the excellent import-cost package (also available as VS Code plugin). This tool will create a mini project, that imports precisely the requested imports using production tree-shaking settings.

This is not only useful to monitor your app's size budget, but also when you are maintaining a library. Especially in "report" mode, see below

Examples

$ npx import-size mobx autorun observable computed action
13337

Using only autorun, observable, computed and action from "MobX" will result in 13 KB (gzipped) being added to your bundle

$ npx import-size mobx '*'
15850

Importing the full MobX api will take 2KB more (so clearly it is not super good at tree-shaking (yet!))

You can also point the tool at any local directory that contains a module source. For example, running npx import-size . autorun in the MobX directory will measure the size of autorun in the directory in which you run this command. (Do make sure that the library has been build locally in the latter case)

To measure the size of a default export, just pass in default as method name.

To measure the size of all exports, pass in *. To prevent bash expanding this into a bunch of file names, you will typically have to quote it like: '*'.

The sizes displayed are gzipped and include transitive dependencies (regardless whether these deps are shared with other libs). Sizes are always a few (~20) bytes off due to utility code that is injected.

Report mode

Report mode can break down the costs of a library as you import more and more of it's features:

$ import-size --report immer produce enableES5 enablePatches enableMapSet

Import size report for immer:
┌────────────────────────┬───────────┬────────────┬───────────┐
│        (index)         │ just this │ cumulative │ increment │
├────────────────────────┼───────────┼────────────┼───────────┤
│ import * from <module> │   6684    │     0      │     0     │
│        produce         │   4024    │    4024    │     0     │
│       enableES5        │   2428    │    4895    │    871    │
│     enablePatches      │   1840    │    5666    │    771    │
│      enableMapSet      │   4915    │    6489    │    823    │
└────────────────────────┴───────────┴────────────┴───────────┘
(this report was generated by npmjs.com/package/import-size)

The report mode first reports the cost of doing a 'side effect import' and a '*' (everything) import.

The rows after that show the import sizes of all mentioned imports:

1. individually in the first column
2. combined with the above rows
3. the delta of that

So the above report shows that just importing enablePatches from 'immer' will cost you 1840 bytes. But, it will cost only an additional 871 bytes if you are already importing produce and enableES5 anyway. In other words, if you just use produce from Immer it will arrive at 4KB, and the three additional opt-in features will all come at roughly 1 additional KB (note that those numbers are not accurate for Immer, they are just a demonstration).

Also note that the order of arguments does matter for the cumulatives and increment columns, so you typically want to put the imports in an order that make sense to future library users. Reports like these might be useful in documentation.

import-size's Issues

Include 0-import cost

It would be great if it could also always report 0-import cost. What I mean is basically always also trying entry with this:

import-size/index.js

Line 12 in 8fc7d17

return `import "${library}";`;

It would serve as a good basic test for treeshakeability as a whole. To get reliable tests for this we'd have to remove sideEffects: false from the imported module - or force webpack to ignore it. Otherwise, it most likely would always report 0, even for non-treeshakeable modules.

Feature request package.json & programmatic usage

First of all this seems like an amazing module! Amazing job!

1. It would be pretty awesome if the vscode plugin could show approx. module sizes from package.json for an overview. I realise it might depend on what you use from the module but it could be something like 'from x kb to y kb' perhaps? (if this one is done I probably don't even need point 2 :P)

2. Also I would like to build further from this, is it possible to use this programmatically? If so could it be mentioned in docs? Something like?

   import importSize from 'import-size'

   importSize.calculate('react-dom', { options } )

Update dependencies

some sub dependencies are outdated or deprecated, could you update all you dependencies plz?

Crash when using multiple imports

So these two commands will work as intended:

npx import-size --report powerbi-client
npx import-size --report highcharts

I've tried a few other packages and they all work fine. But when I supply multiple packages, it goes south:

> npx import-size --report highcharts powerbi-client

Creating build 2/3
Error: Invalid import: 'powerbi-client'
    at C:\...\npm-cache\_npx\8db025f95d6e6ad3\node_modules\import-size\index.js:26:13
    at Array.forEach (<anonymous>)
    at generateImports (C:\...\npm-cache\_npx\8db025f95d6e6ad3\node_modules\import-size\index.js:24:16)
    at C:\...\npm-cache\_npx\8db025f95d6e6ad3\node_modules\import-size\index.js:45:7
    at new Promise (<anonymous>)
    at analyze (C:\...\npm-cache\_npx\8db025f95d6e6ad3\node_modules\import-size\index.js:41:10)
    at runReport (C:\...\npm-cache\_npx\8db025f95d6e6ad3\node_modules\import-size\index.js:168:26)

I'm on Windows 10, regular command prompt, Node.js 16.18.0, npm 8.19.2.
Npx is just using the latest published version of import-size, iinm.

react-dom is reporting 0

❯ npx import-size react-dom
0

reports `0` on @vue/runtime-dom

Something seems different with that project. Not sure yet why

https://twitter.com/youyuxi/status/1228811177838379016