CD2H gitForager

FormidableLabs/inspectpack

Name: inspectpack

Owner: Formidable

Description: An inspection tool for Webpack frontend JavaScript bundles.

Created: 2016-03-20 23:30:03.0

Updated: 2018-01-15 18:11:28.0

Pushed: 2017-10-13 18:18:37.0

Homepage: null

Size: 598

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

inspectpack

An inspection tool for Webpack frontend JavaScript bundles.

Inspectpack gives insight into what's in your production JS bundles and where you can cut down on size, duplicates, etc.

Install

m install inspectpack

Usage

nspection tool for Webpack frontend JavaScript bundles.

e: inspectpack --action=<string> [options]

ons:
action, -a        Actions to take
   [string] [required] [choices: "duplicates", "pattern", "parse", "files", "versions", "sizes"]
bundle, -b        Path to webpack-created JS bundle                                     [string]
root, -r          Project root (for `node_modules` introspection, default cwd)          [string]
format, -f        Display output format
                                     [string] [choices: "json", "text", "tsv"] [default: "text"]
verbose           Verbose output                                      [boolean] [default: false]
minified, -m      Calculate / display minified byte sizes              [boolean] [default: true]
gzip, -g          Calculate / display minified + gzipped byte size (implies `--minified`)
                                                                       [boolean] [default: true]
allow-empty       Allow unparseable / empty bundles                   [boolean] [default: false]
pattern, -p       Regular expression string(s) to match on                 [array] [default: []]
path              Path to input file(s)                                    [array] [default: []]
suspect-patterns  Known 'suspicious' patterns for `--action=pattern`                   [boolean]
suspect-parses    Known 'suspicious' code parses for `--action=parse`                  [boolean]
suspect-files     Known 'suspicious' file names for `--action=files`                   [boolean]
duplicates        Filter `--action=versions` to libraries that cannot be deduped       [boolean]
help, -h          Show help                                                            [boolean]
version, -v       Show version number                                                  [boolean]

ples:
spectpack --action=duplicates --bundle=bundle.js  Report duplicates that cannot be deduped
spectpack --action=pattern --bundle=bundle.js     Show files with pattern matches in code
suspect-patterns
spectpack --action=versions --bundle=bundle.js    Show version skews in a project
root=/PATH/TO/project
spectpack --action=parse --bundle=bundle.js       Show files with parse function matches in code
suspect-parses
spectpack --action=files --bundle=bundle.js       Show files with pattern matches in file names
suspect-files

Inputs

The are three potential sources of input for bundle analysis:

Stats: A metadata file of build / size information generated by Webpack
Source Maps: The source mappings file for a bundle
Bundle: And of course, the JS bundle itself.

Additionally, specific analysis steps also may require designated Webpack configurations to produce a proper input.

Bundle

If an inspectpack action requires a --bundle, create one as follows:

Webpack configuration:

Enable deduplication: plugins:webpack.optimize.DedupePlugin()
Disable minification: We need the comment headers.
Enable output path comments: output.pathinfo = true.

Inputs: Create a JavaScript bundle

bpack

The created JS bundle path is ready to use. (Note that code split chunks should work same as a single root bundle, but we haven't tested this yet.)

Actions

`duplicates`

Detect if there are libraries that should be de-duplicated with the webpack.optimize.DedupePlugin but are not because of version mismatches.

First create a bundle. Then run:

spectpack --action=duplicates --bundle=bundle.js

Outputs: A JSON, text, or tab-separate-value report. For example:

ummary

ndle:
* Path:                /PATH/TO/bundle.js
* Bytes (min):         1678533
ssed Duplicates:
* Num Unique Files:    116
* Num Extra Files:     131
* Extra Bytes (min):   253955
* Pct of Bundle Size:  15 %

Number of unique files with missed duplicates.
Number of total files that could be removed. This is different from the previous number because you may have 3+ duplicates of a unique file path that cannot be deduplicated.
Minified byte size of the extra files. Note that we choose the “minimum possible code size” to be the lowest of all file sizes for a given unique file name.

Notes:

The vast majority of the analysis time is spent minifying and gzipping duplicate code snippets and the entire bundle. For just a list of missed duplicates, add the --minified=false --gzip=false flags.

`versions`

Examine all of the modules in node_modules that are used in 1+ files in the bundle and detect version skews. Many downstream modules require the same upstream modules at different versions and this can create inefficiencies if those common dependencies cannot be deduplicated (detected by --action=duplicates). This feature figures out:

Any skewed version dependencies for a given library. This is important because we want to ideally make sure that only one version of a library is used.
If that library has upstream dependencies that are themselves skewed. This is important additional data because it tells us if this module depends on other modules that have skews that you should resolve first.

With these two pieces of data, we can then look at our dependency graph for a given application and manually harmonize module versions. The key here is to start with modules that have no upstream skews, and accordingly the versions action produces reports that are sorted by lowest number of upstream skews.

Let's see this in action…

First create a bundle. Then run:

spectpack --action=versions --bundle=bundle.js --root=/PATH/TO/project

Outputs: A JSON, text, or tab-separate-value report. For example:

ectpack --action=versions
=========================

ummary

ndle:
* Path:                /PATH/TO/bundle.js
* Num Libs:            17

ibraries


dash
Skewed Deps: 0

Versions: 2
* 4.12.0:
  * root -> cabal-event@3.1.0
  * root -> foo-buzz-util@1.2.0
  * root -> foo-footer@5.5.6 -> foo-forms@4.0.1 -> foo-validation@2.1.1
  ...
* 3.10.1:
  * root
  * root -> my-ui-config@1.3.1
  * root -> foo-containers@8.1.2 -> foo-interactive@6.0.3
  * root -> a11y@1.0.3 -> foo-carousel@2.0.0 -> foo-interactive@5.2.0
  * root -> a11y@1.0.3 -> babar-card@6.7.3
  * root -> a11y@1.0.3 -> babar-card@6.7.3 -> babar-buttons@5.7.1 -> foo-forms@2.0.1 -> foo-base@2.1.1 -> foo-layout@2.0.2 -> foo-validation@0.2.5
  * root -> a11y@1.0.3 -> babar-card@6.7.3 -> babar-descriptors@2.0.0
  ...



bal-event
Skewed Deps: 1
* lodash

Versions: 2
* 3.1.0:
  * root
  * root -> foo-footer@5.5.6
  * root -> foo-footer@5.5.6 -> foo-tutils@3.0.1
  * root -> foo-header@6.11.1
* 2.1.0:
  * root -> a11y@1.0.3

The above truncated report tells us that we have 17 module dependencies that have at least 2+ version skews in our project. The lodash module has 0 “Skewed Deps” upstream dependencies and there are two versions of the library ending up in the bundle: 4.12.0 and 3.10.1. Having no upstream skews means we should fix these skews first in our project before moving to modules that have 1+ upstream skews. By contrast, the cabal-event module has 1 skewed upstream dependency on lodash, which illustrates that we should wait until lodash is resolved before moving on to harmonize versions in that module.

Notes:

The versions action provides a --duplicates flag to only list version skews for code chunks that are missed deduplication opportunities. This is a good prioritization step to take since different module versions may still have the exact same code files in the resulting bundle, which can be deduplicated and thus aren't a real concern for code size / execution speed in optimizing your bundle.
The --root flag needs to point to the webpack configuration context value, which defaults to process.cwd() for both webpack and inspectpack.

`sizes`

Get a simple report of each file chunk in a bundle with the type of chunk and relevant sizes (full, min, min+gz).

First create a bundle. Then run:

spectpack --action=sizes --bundle=bundle.js

Outputs: A JSON, text, or tab-separate-value report. For example:

ummary

ndle:
* Path:                    /PATH/TO/bundle.js
* Bytes (min):             1584818
* Bytes (min+gz):          367026

iles
/app.jsx
Type:          code
Size:          5439
Size (min):    2314
Size (min+gz): 1002

./~/babel-polyfill/lib/index.js
Type:          code
Size:          1423
Size (min):    658
Size (min+gz): 422

Notes:

The vast majority of the analysis time is spent minifying and gzipping code snippets and the entire bundle. To skip these sizes for a faster report, add the --minified=false --gzip=false flags.

`parse`

Detect the occurrence of 1+ code parse function matches in code sections of the bundle. This is another means of detecting anti-patterns, some of which we aggregate in --suspect-parses.

Note: This is simply a more abstract version of pattern where you could have a parse function that uses the same regex to match a code snippet manually. What this feature really opens up is full Babel traversals / introspection, which are more correct and flexible than anything regular expressions can do. In our --suspect-parses collection, we use babel introspection to very tightly determine if there are multiple exports in any source code file in a bundle.

First create a bundle.

Next, decide if using provided --suspect-parses or your own custom parse functions with one or more file paths to --path. A parse function should follow these guidelines:


heck if source matches selection criteria.

param   {String}      src Source code snippet
returns {String|null}     String snippet match or falsy if no match

le.exports = function (src) {
 Find a occurrences of token "first" and return containing line.
turn (src.match(/^.*first.*$/m) || [])[0];

In this simple example, we're just using regular expressions, but for complex projects / investigations you'll likely want to step up to some Babel magic.

Then run:

custom parse file
spectpack \
action=parse --bundle=bundle.js \
path=/PATH/TO/parse.js

spect parses
spectpack \
action=parse --bundle=bundle.js \
suspect-parses

Suspect Parses: The --suspect-parses flag looks for known “suspect” code snippets that potentially contain inefficient code. See the source code for the full breakdown of SUSPECT_PARSES.

MULTIPLE_EXPORTS: Multiple exports via any number export objects / statements.

ingle object.
le.exports = {
o: __webpack_require__(1),
r: __webpack_require__(2)


ultiple statements.
le.exports.foo = __webpack_require__(1);
le.exports.bar = __webpack_require__(2);

Outputs: A JSON, text, or tab-separate-value report. For example:

spectpack \
action=parse \
bundle="/PATH/TO/bundle.js" \
format=text \
suspect-parses
ectpack --action=parse
========================

ummary

ndle:
* Path:                /Users/rye/scm/fmd/simple-proj/dist/bundle.js
* Num Matches:         3
* Num Unique Files:    3
* Num All Files:       3
* Custom Parses:
* Suspect Parses:
    * MULTIPLE_EXPORTS

atches

lib/mod-a.js
* Num Matches:         1
* Num Files Matched:   1

* 1: ./lib/mod-a.js
    * Matches: 1
        * MULTIPLE_EXPORTS:
            module.exports = {
              first: __webpack_require__(/*! ./first */ 2),
              second: __webpack_require__(/*! ./second */ 3)
            };


lib/mod-b.js
* Num Matches:         1
* Num Files Matched:   1

* 4: ./lib/mod-b.js
    * Matches: 1
        * MULTIPLE_EXPORTS:
            module.exports.first = __webpack_require__(/*! ./first */ 2);
          // ...
            module.exports.second = __webpack_require__(/*! ./second */ 3);

`pattern`

Detect the occurrence of 1+ patterns in code sections of the bundle. This is useful for detecting anti-patterns, some of which we aggregate in a useful option --suspect-patterns.

Note: There is a good deal of overlap with parse in suspect patterns, were we're doing the same thing with different approaches (code parsing vs regex grepping). In general, parsing is far more powerful and correct. But, there's always a use for quick and dirty regular expressions which we discuss further in this section.

First create a bundle. Then run:

single pattern
spectpack \
action=pattern --bundle=bundle.js \
pattern="201[56]"

ltiple patterns
spectpack \
action=pattern --bundle=bundle.js \
pattern "2016" "unicorn"

spect patterns
spectpack \
action=pattern --bundle=bundle.js \
suspect-patterns

Notes:

It is best to use quotes around patterns so that you don't have to escape shell processing.
Some regular expressions can be very expensive time-wise, so be sure to try things out a bit and refactor your patterns if the inspection is taking too long.

Suspect Patterns: The --suspect-patterns flag looks for known “suspect” patterns that potentially contain inefficient code. See the source code for the full breakdown of SUSPECT_PATTERNS.

MULTIPLE_EXPORTS_SINGLE: Multiple exports via one export object.

le.exports = {
o: __webpack_require__(1),
r: __webpack_require__(2)

MULTIPLE_EXPORTS_MUTIPLE: Multiple exports via 2+ export statements.

le.exports.foo = __webpack_require__(1);
le.exports.bar = __webpack_require__(2);

Outputs: A JSON, text, or tab-separate-value report. For example:

spectpack \
action=pattern \
bundle="/PATH/TO/bundle.js" \
format=text \
suspect-patterns

ummary

ndle:
* Path:                /PATH/TO/bundle.js
* Num Matches:         17
* Num Unique Files:    14
* Num All Files:       17
* Custom Patterns:
* Suspect Patterns:
    * MULTIPLE_EXPORTS_SINGLE: [^\n]*(module\.|)exports\s*=\s*{(\s*.*__webpack_require__\(.*){2}
    * MULTIPLE_EXPORTS_MUTIPLE: [^\n]*((module\.|)exports\..*\s*=\s*.*__webpack_require__\(.*\s*){2}

atches

stom-lib/lib/index.js
* Num Matches:         1
* Num Files Matched:   1

* 1103: ../~/custom-lib/lib/index.js
    * Matches: 1
        * MULTIPLE_EXPORTS_SINGLE - /[^\n]*(module\.|)exports\s*=\s*{(\s*.*__webpack_require__\(.*){2}/:
            module.exports = {
              Foo: __webpack_require__(/*! ./components/foo */ 1104),
              Bar: __webpack_require__(/*! ./components/bar */ 1135),

dash/string.js
* Num Matches:         1
* Num Files Matched:   1

* 1581: ../~/lodash/string.js
    * Matches: 1
        * MULTIPLE_EXPORTS_SINGLE - /[^\n]*(module\.|)exports\s*=\s*{(\s*.*__webpack_require__\(.*){2}/:
            module.exports = {
              'camelCase': __webpack_require__(/*! ./string/camelCase */ 1582),
              'capitalize': __webpack_require__(/*! ./string/capitalize */ 1587),


dash/lang.js
* Num Matches:         1
* Num Files Matched:   1

* 1862: ../~/lodash/lang.js
    * Matches: 1
        * MULTIPLE_EXPORTS_SINGLE - /[^\n]*(module\.|)exports\s*=\s*{(\s*.*__webpack_require__\(.*){2}/:
            module.exports = {
              'clone': __webpack_require__(/*! ./lang/clone */ 1863),
              'cloneDeep': __webpack_require__(/*! ./lang/cloneDeep */ 1869),

`files`

Detect the occurrence of 1+ files by the base name (resolved from node_modules). This is useful for detecting anti-patterns based on files that should never be part of a webpack bundle. We aggregate useful file patterns in the option --suspect-files.

First create a bundle. Then run:

single file pattern
spectpack \
action=files --bundle=bundle.js \
pattern="underscore"

ltiple file patterns
spectpack \
action=files --bundle=bundle.js \
pattern "underscore" "jquery"

spect files
spectpack \
action=files --bundle=bundle.js \
suspect-files

Suspect Files: The --suspect-files flag looks for known “suspect” file patterns that potentially contain inefficient code. See the source code for the full breakdown of SUSPECT_FILES.

LODASH: Known lodash files that have multiple exports. You should instead import “one-off” files.
MOMENT_LOCALE_ROOT: A webpack pattern that signals every possible locale is bundled in your application. You should instead hone down and include only the locales that you specifically need for your application.

Outputs: A JSON, text, or tab-separate-value report. For example:

ectpack --action=files
======================

ummary

ndle:
* Path:                /PATH/TO/bundle.js
* Num Matches:         4
* Num Files:           4
* Custom Patterns:
    * underscore\/
* Suspect Patterns:
    * LODASH: lodash/(index|lodash|lodash\.min|array|collection|date|function|lang|math|number|object|seq|string|util)\.js
    * MOMENT_LOCALE_ROOT: moment\/locale \^\\\.\\\/\.\*\$

iles
* lodash/index.js
* underscore/underscore.js
* lodash/lang.js
* moment/locale ^\.\/.*$

atches

dash/index.js
* Matches:            1
    * LODASH - /lodash\/(index|lodash|lodash\.min|array|collection|date|function|lang|math|number|object|seq|string|util)\.js/: lodash/index.js
* Refs:
    * 1400: ../~/foo/~/lodash/index.js

derscore/underscore.js
* Matches:            1
    * CUSTOM - /underscore\//: underscore/
* Refs:
    * 2650: ../~/bar/~/underscore/underscore.js

dash/lang.js
* Matches:            1
    * LODASH - /lodash\/(index|lodash|lodash\.min|array|collection|date|function|lang|math|number|object|seq|string|util)\.js/: lodash/lang.js
* Refs:
    * 2820: ../~/baz/~/lodash/lang.js

ment/locale ^\.\/.*$
* Matches:            1
    * MOMENT_LOCALE_ROOT - /moment\/locale \^\\\.\\\/\.\*\$/: moment/locale ^\.\/.*$
* Refs:
    * 2855: ../~/moment/locale ^\.\/.*$

Other Useful Tools

Other tools that inspect Webpack bundles:

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.