# packtracker.io webpack plugin
[](https://travis-ci.org/packtracker/webpack-plugin)
[](https://coveralls.io/github/packtracker/webpack-plugin?branch=master)
[](https://app.codacy.com/app/jondavidjohn/webpack-plugin)
[](https://standardjs.com)
This plugin is designed to upload your webpack build stats to the [packtracker.io](https://packtracker.io) service.
## Installation
Once you have your [project created](https://docs.packtracker.io/creating-your-first-project) on [packtracker.io](https://app.packtracker.io), and a `project_token` in hand, you can get your data flowing by installing and configuring this plugin.
```sh
npm install --save-dev @packtracker/webpack-plugin
```
## Usage
### Webpack Plugin
In your webpack configuration include the plugin (along with your project token).
> If the plugin fails to upload your stats, **it will not error out your build** but it will **log output signaling the failure**.
```js
const PacktrackerPlugin = require('@packtracker/webpack-plugin')
module.exports = {
plugins: [
new PacktrackerPlugin({
project_token: '',
upload: true
})
]
}
```
The `upload` option above tells the plugin whether or not to upload your build stats when running webpack. By default, this option is set to `false` to prevent accidental uploading from your local machine. If the upload option is left `false`, the plugin will do nothing.
Once you see your stats are uploading, it is common to only upload when building your assets in a CI environment or during deployment. You can also omit this option altogether, and set the `PT_UPLOAD` environment variable on a per run basis to control the upload of your stats.
For example
```js
const PacktrackerPlugin = require('@packtracker/webpack-plugin')
module.exports = {
plugins: [
new PacktrackerPlugin({
project_token: '',
upload: process.env.CI === 'true'
})
]
}
```
### CLI
In addition to the primary use case of uploading as part of your build process via our webpack plugin, we also have a command line uploader that works well with tools like [create-react-app](https://facebook.github.io/create-react-app/) that allow you to export your stats, but don't allow full plugin configuration.
The only caveat to using the CLI is that you **must** use environment variables to configure your stat reporting (most importantly `PT_PROJECT_TOKEN`).
#### Example with `create-react-app`
In your `package.json` you can add a run script like the following
```json
{
"scripts": {
"packtracker": "react-scripts build --stats && packtracker-upload --stats=build/bundle-stats.json"
}
}
```
The only additional parameter you can pass via the CLI is the `--output-path=`, if it is not passed we assume it is the directory that contains your bundle stats file.
Then running `npm run packtracker` should upload your stats to our service
### Options
All of the options, available to the plugin can be set [via argument to the plugin, environment variable, or allowed to query your local git repository.](https://github.com/packtracker/webpack-plugin/blob/master/config.js)
Here is a listing of the plugin options, environment variable counterparts, and a description.
| Option | Env Variable | Description
|---------------- |---------------------|------------
|`project_token` | `PT_PROJECT_TOKEN` | The project token for your packtracker.io project (required)
|`fail_build` | `PT_FAIL_BUILD` | Fail the build if the stat upload fails (default: `false`)
|`branch` | `PT_BRANCH` | Branch of the commit
(default: `git rev-parse --abbrev-ref HEAD`)
|`author` | `PT_AUTHOR` | Committer's email (default: `git log --format="%aE" -n 1 HEAD`)
|`message` | `PT_MESSAGE` | The commit message (default: `git log --format="%B" -n 1 HEAD`)
|`commit` | `PT_COMMIT` | The commit sha (default: `git rev-parse HEAD`)
|`committed_at` | `PT_COMMITTED_AT` | Unix timestamp (ms) of the commit
(default: `git log --format="%ct" -n 1 HEAD`)
|`prior_commit` | `PT_PRIOR_COMMIT` | The previous commit sha (default: `git rev-parse HEAD^`)
|`exclude_assets` | `PT_EXCLUDE_ASSETS` | Mirrors the [excludeAssets configuration in the webpack stats config](https://webpack.js.org/configuration/stats/#stats) (only available to webpack version 3.5.0+) (compiled as RegExp when provided via environment variable)
You can find more documentation about the packtracker.io service in general at [https://docs.packtracker.io](https://docs.packtracker.io)