# Webpack Bundle Tracker

[![master build status](https://github.com/django-webpack/webpack-bundle-tracker/actions/workflows/config.yml/badge.svg)](https://github.com/django-webpack/webpack-bundle-tracker/actions/workflows/config.yml)

Spits out some stats about webpack compilation process to a file.

## Install

```bash
npm install --save-dev webpack-bundle-tracker
```

## Compatibility

This project is compatible with NodeJS versions 16 and up.

:warning: Starting on version 17, NodeJS uses OpenSSL v3 which has compatibility issues with Webpack@4. This isn't an issue for Webpack@5, however
if you're using Node >= 17 and Webpack@4, to properly use this package you must ensure to set the `NODE_OPTIONS=--openssl-legacy-provider` environment
variable. You can read more about this on https://github.com/webpack/webpack/issues/14532.

## Migrating from version 1.x.y to 2.x.y

Starting on version 2.0.0, when creating a new instance of `BundleTracker`, the usage of the `path` parameter has been fixed and it's now being used to generate the output path for the stats file, together with the `filename` parameter. On version 2.0.0, if the `path` parameter is ommited from the constuctor call, it will attempt to place the stats file at the `output.path` directory (if also ommited, will use `'.'` as a fallback). Also, version 2.0.0 doesn't allow sub-directories to be included on the `filename`, only allowing to include them on the `path` param. To avoid those issues, when migrating, double-check if the file placement is as expected. The usage of these parameters is documented [here](#usage) and [here](#options).

## Usage

```javascript
var path = require('path');
var BundleTracker = require('webpack-bundle-tracker');
module.exports = {
  context: __dirname,
  entry: {
    app: ['./app'],
  },

  output: {
    path: path.resolve('./assets/bundles/'),
    filename: '[name]-[hash].js',
    publicPath: 'http://localhost:3000/assets/bundles/',
  },

  plugins: [
    new BundleTracker({
      path: path.join(__dirname, 'assets'),
      filename: 'webpack-stats.json',
    }),
  ],
};
```

The `webpack-stats.json` file will look like,

```json
{
  "status": "done",
  "chunks": {
    "app": ["app-0828904584990b611fb8.js"]
  },
  "assets": {
    "app-0828904584990b611fb8.js": {
      "name": "app-0828904584990b611fb8.js",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js",
      "path": "/home/user/project-root/assets/bundles/app-0828904584990b611fb8.js"
    }
  }
}
```

In case webpack is still compiling, it'll look like,

```json
{
  "status": "compile"
}
```

And errors will look like,

```json
{
  "status": "error",
  "file": "/path/to/file/that/caused/the/error",
  "error": "ErrorName",
  "message": "ErrorMessage"
}
```

`ErrorMessage` shows the line and column that caused the error.

And in case `logTime` option is set to `true`, the output will look like,

```json
{
  "status": "done",
  "chunks": {
    "app": ["app-0828904584990b611fb8.js"]
  },
  "assets": {
    "app-0828904584990b611fb8.js": {
      "name": "app-0828904584990b611fb8.js",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js",
      "path": "/home/user/project-root/assets/bundles/app-0828904584990b611fb8.js"
    }
  },
  "startTime": 1440535322138,
  "endTime": 1440535326804
}
```

And in case `relativePath` option is set to `true`, the output will look like,

```json
{
  "status": "done",
  "chunks": {
    "app": ["app-0828904584990b611fb8.js"]
  },
  "assets": {
    "app-0828904584990b611fb8.js": {
      "name": "app-0828904584990b611fb8.js",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js",
      "path": "app-0828904584990b611fb8.js"
    }
  }
}
```

And in case `integrity` option is set to `true`, the output will look like,

```json
{
  "status": "done",
  "chunks": {
    "app": ["app-0828904584990b611fb8.js"]
  },
  "assets": {
    "app-0828904584990b611fb8.js": {
      "name": "app-0828904584990b611fb8.js",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js",
      "path": "app-0828904584990b611fb8.js",
      "integrity": "sha256-yAIefNWsF0IfxalAlLNngdY0t3J1h4IzZLzcJEn/FTM= sha384-QmiRCOdQx6MVC721liFMbJjud6Kr5ryT1vhHI5htzftpzoI1P3IlBqbpg5AHjbBv sha512-kbLjakids0Z2vvrOrtV7s2FUvKcgM3bg0WQwuyGvJPE+zVqOL4t0UvWkeUzz5z2ZrDm0ST/dQjPBJaq7rDB/2Q=="
    }
  }
}
```

And in case of usage of compression plugin for webpack, the output will look like,

```json
{
  "status": "done",
  "chunks": {
    "app": ["app-0828904584990b611fb8.js"]
  },
  "assets": {
    "app-0828904584990b611fb8.js": {
      "name": "app-0828904584990b611fb8.js",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js",
      "path": "/home/user/project-root/assets/bundles/app-0828904584990b611fb8.js"
    },
    "app-0828904584990b611fb8.js.br": {
      "name": "app-0828904584990b611fb8.js.br",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js.br",
      "path": "/home/user/project-root/assets/bundles/app-0828904584990b611fb8.js.br"
    },
    "app-0828904584990b611fb8.js.gz": {
      "name": "app-0828904584990b611fb8.js.gz",
      "publicPath": "http://localhost:3000/assets/bundles/app-0828904584990b611fb8.js.gz",
      "path": "/home/user/project-root/assets/bundles/app-0828904584990b611fb8.js.gz"
    }
  }
}
```

By default, the output JSON will not be indented. To increase readability, you can use the `indent`
option to make the output legible. By default it is off. The value that is set here will be directly
passed to the `space` parameter in `JSON.stringify`. More information can be found [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)

## Options

| Name              | Type        | Default                          | Description                                                                                                                     |
| ----------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `path`            | `{String}`  | `'.'`                            | Output directory of bundle tracker JSON file. Will attempt to use `output.path` before falling back to the default value.       |
| `filename`        | `{String}`  | `'webpack-stats.json'`           | Name of the bundle tracker JSON file.                                                                                           |
| `publicPath`      | `{String}`  | (ignored)                        | Override `output.publicPath` from Webpack config.                                                                               |
| `relativePath`    | `{Boolean}` | `false`                          | Show relative path instead of absolute path for bundles in JSON Tracker file. Path are relative from path of JSON Tracker file. |
| `logTime`         | `{Boolean}` | `false`                          | Output `startTime` and `endTime` properties in bundle tracker JSON file.                                                        |
| `integrity`       | `{Boolean}` | `false`                          | Output `integrity` property for each asset entry.                                                                               |
| `integrityHashes` | `{Array}`   | `['sha256', 'sha384', 'sha512']` | Cryptographic hash functions used to compute integrity for each asset.                                                          |
| `indent`          | `{Integer}` | `undefined`                      | Format resulting JSON file for better readability.                                                                              |