This webpack-plugin generates statoscope HTML-report from webpack-stats.

npm install @statoscope/webpack-plugin --save-dev

webpack.config.js:

const StatoscopeWebpackPlugin = require('@statoscope/webpack-plugin').default;

config.plugins.push(new StatoscopeWebpackPlugin());

There are some options:

new StatoscopeWebpackPlugin({
  saveReportTo: 'path/to/report-[name]-[hash].html',
  saveStatsTo: 'path/to/stats-[name]-[hash].json',
  normalizeStats: false,
  saveOnlyStats: false,
  disableReportCompression: false,
  statsOptions: {
    /* any webpack stats options */
  },
  additionalStats: ['path/to/any/stats.json'],
  watchMode: false,
  name: 'some-name',
  open: 'file',
  compressor: 'gzip',
  reports: [/* ... */],
  extensions: [/* ... */],
});

Path to an HTML with a report.

By default is a temporary directory with filename: statoscope-[name]-[hash].html

[name] replacing by options.name (if specified) or compilation.name (if specified) or unnamed

[hash] replacing by compilation.hash

A path for saving the stats: stats-[name]-[hash].json

[name] replacing by options.name (if specified) or compilation.name (if specified) or unnamed

[hash] replacing by compilation.hash

By default don't save anything

Reduce stats size that will be saved into saveStatsTo.

false by default

Note that normalized stats will be handled correctly only by Statoscope

If true then only json with the stats will be generated. HTML report will be omitted.

false by default.

If true then html report data compression will be disabled. It increases html size a lot. Use it only when something is wrong with report in a browser.

false by default.

With statsOptions you can override your webpack-config stats option

For example: statsOptions: { all: true, source: false }

If not specified (by default) then stats options from your webpack config will be used.

All stats-options see at docs

List with the paths to webpack stats that will be loaded into Statoscope along with current compilation stats.

In UI, you could switch between them or diff.

const glob = require('glob');

new StatoscopeWebpackPlugin({
  saveStatsTo: 'path/to/stats/stats-[name]-[hash].json',
  additionalStats: glob.sync('path/to/stats/*.json'),
});

In this example, the stats from every compilation will be saved into path/to/stats/ directory.

Also, all JSON files from path/to/stats/ directory will be added to the Statoscope report.

In this way, you can collect the stats from all compilations and diff these to find out how your bundle was changing in time.

By default, Statoscode does not generate a report if the webpack runs in watch-mode.

Set watchMode: true to generate a report in watch-mode

Custom compilation name.

By default compilation.name (if specified)

Open report after compilation.

• false - don't open report
• file - open html with report
• dir - open a directory with html file

file by default.

Collect compressed (e.g. gzip) size of the resources (assets and modules).

• 'gzip' (default) - compress all the resources with gzip and collect the compressed sizes
• ['gzip', ZlibOptions] - the same as above but with custom zlib settings

  new Statoscope({
      compressor: ['gzip', {level: 9}]
  })

• CompressFunction - a function that takes source as an input and should return compressed size for this resource (useful if you want to use non-gzip compressor)
• false - don't collect compressed sizes

new Statoscope({
  compressor(source: Buffer | string, filename: string) {
    const compressed = customCompressor(source);
    return {
      compressor: 'my-custom-compressor',
      size: compressed.length
    }
  }
})

List of custom reports that will be passed into the UI.

See report format in stats-extension-custom-reports readme.

Example:

new Statoscope({
  reports: [
    {
      id: 'top-20-biggest-modules',
      name: 'Top 20 biggest modules',
      data: { some: { custom: 'data' } }, // or () => fetchAsyncData()
      view: [
        'struct',
        {
          data: `#.stats.compilations.(
            $compilation: $;
            modules.({
              module: $,
              hash: $compilation.hash,
              size: getModuleSize($compilation.hash)
            })
          ).sort(size.size desc)[:20]`,
          view: 'list',
          item: 'module-item',
        },
      ],
    },
  ],
});

List of stats extension webpack adapters.

This options helps you to pass your own webpack stats extensions.

For example, lets implement simple extension that gets webpack compiler context directory.

webpack-context-extension.ts:

import { Extension } from '@statoscope/stats/spec/extension';

type Payload = {
  context: string
};

type ContextExtension = Extension<Payload>;

export default class WebpackContextExtension implements StatsExtensionWebpackAdapter<Payload> {
  context: string = '';

  handleCompiler(compiler: Compiler): void {
    this.context = compiler.context;
  }

  getExtension(): ContextExtension {
    return {
      descriptor: {name: 'webpack-context-extension', version: '1.0.0'},
      payload: {context: this.context}
    }
  }
}

webpack.config.js:

const WebpackContextExtension = require('./webpack-context-extension');
const StatoscopeWebpackPlugin = require('@statoscope/webpack-plugin').default;

config.plugins.push(new StatoscopeWebpackPlugin({
  extensions: new WebpackContextExtension()
}));

Now you can handle your extension payload with jora:

$ext: 'webpack-context-extension'.resolveExtension(@.name.pick()).data;
$webpackContext: $ext.payload.context;

resolveExtension-helper resolves an extension by its name and a filename that extension attached to

⚠️ Most often the default stats settings is enough, but you can also adjust the size of the report by enabling or disabling various stats flags.

Statoscope use only stats that it has. There is only one required flag - hash.

stats: {
  all: false, // disable all the stats
  hash: true, // add a compilation hash
}

It works, but useless, because the result stats is empty.

You could disable some stats-flags to decrease your stats-file size. Here is a set of minimum useful stats flags:

stats: {
  all: false, // disable all the stats
  hash: true, // compilation hash
  entrypoints: true, // entrypoints
  chunks: true, // chunks
  chunkModules: true, // modules
  reasons: true, // modules reasons,
  ids: true, IDs of modules and chunks (webpack 5)
},

And an example of more useful stats:

stats: {
  all: false, // disable all the stats
  hash: true, // compilation hash
  entrypoints: true, // entrypoints
  chunks: true, // chunks
  chunkModules: true, // modules
  reasons: true, // modules reasons
  ids: true, // IDs of modules and chunks (webpack 5)
  dependentModules: true, // dependent modules of chunks (webpack 5)
  chunkRelations: true, // chunk parents, children and siblings (webpack 5)
  cachedAssets: true, // information about the cached assets (webpack 5)


  nestedModules: true, // concatenated modules
  usedExports: true, // used exports
  providedExports: true, // provided imports
  assets: true, // assets
  chunkOrigins: true, // chunks origins stats (to find out which modules require a chunk)
  version: true, // webpack version
  builtAt: true, // build at time
  timings: true, // modules timing information
  performance: true, // info about oversized assets
},

You could also add source: true. It adds modules source into stats (to find modules duplicates) but increases stats file size

Just specify a context to stats options:

stats: {
  context: 'path/to/project/root'
}

If you are an engineer or a company that is interested in Statoscope improvements, you could support Statoscope by financial contribution at OpenCollective.