Skip to content
This repository has been archived by the owner on Dec 5, 2019. It is now read-only.

Commit

Permalink
docs(README): standardize
Browse files Browse the repository at this point in the history
  • Loading branch information
@michael-ciniawsky
michael-ciniawsky committed Jul 6, 2017
1 parent cfa6c53 commit 9268e30
Showing 1 changed file with 140 additions and 92 deletions.
232 changes: 140 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,151 +1,199 @@
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![test][test]][test-url]
[![coverage][cover]][cover-url]
[![quality][quality]][quality-url]
[![chat][chat]][chat-url]


<div align="center">
<!-- replace with accurate logo e.g from https://worldvectorlogo.com/ -->
<a href="https://github.com/webpack/webpack">
<img width="200" height="200" vspace="" hspace="25"
<img width="200" height="200"
src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg">
</a>
<h1>UglifyJS Webpack Plugin</h1>
<p>This plugin uses <a href="https://github.com/mishoo/UglifyJS2/tree/v2.x">UglifyJS v2</a> to minify your JavaScript.<p>
<p>This plugin uses <a href="https://github.com/mishoo/UglifyJS2/tree/master">UglifyJS v3</a> to minify your JavaScript<p>
</div>

> Note that webpack contains the same plugin under `webpack.optimize.UglifyJsPlugin`. This is a standalone version for those that want to control the version of UglifyJS. The documentation is valid apart from the installation instructions in that case.
> ℹ️ webpack contains the same plugin under `webpack.optimize.UglifyJsPlugin`. The documentation is valid apart from the installation instructions
<h2 align="center">Install</h2>

With [Yarn](https://yarnpkg.com):

```bash
yarn add uglifyjs-webpack-plugin --dev
```

With npm:

```bash
npm install uglifyjs-webpack-plugin --save-dev
```

**Important!** The plugin has a peer dependency to uglify-js, so in order to use the plugin, also uglify-js has to be installed. The currently (2017/1/25) available uglify-js npm packages; however, do not support minification of ES6 code. In order to support ES6, an ES6-capable, a.k.a. _harmony_, version of UglifyJS has to be provided.

If your minification target is ES6:

```bash
yarn add git://github.com/mishoo/UglifyJS2#harmony-v2.8.22 --dev
```

If your minification target is ES5:

```bash
yarn add uglify-js --dev
npm i -D uglifyjs-webpack-plugin
```

<h2 align="center">Usage</h2>

```javascript
const UglifyJSPlugin = require('uglifyjs-webpack-plugin');
**webpack.config.js**
```js
const UglifyJSPlugin = require('uglifyjs-webpack-plugin')

module.exports = {
entry: {...},
output: {...},
module: {...},
plugins: [
new UglifyJSPlugin()
]
};
}
```

<h2 align="center">Options</h2>

This plugin supports UglifyJS features as discussed below:

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| compress | boolean, object | true | See [UglifyJS documentation](http://lisperator.net/uglifyjs/compress). |
| mangle | boolean, object | true | See below. |
| beautify | boolean | false | Beautify output. |
| output | An object providing options for UglifyJS [OutputStream](https://github.com/mishoo/UglifyJS2/blob/v2.x/lib/output.js) | | Lower level access to UglifyJS output. |
| comments | boolean, RegExp, function(astNode, comment) -> boolean | Defaults to preserving comments containing `/*!`, `/**!`, `@preserve` or `@license`. | Comment related configuration. |
| extractComments | boolean, RegExp, function (astNode, comment) -> boolean, object | false | Whether comments shall be extracted to a separate file, (see [details](https://github.com/webpack/webpack/commit/71933e979e51c533b432658d5e37917f9e71595a), since webpack 2.3.0) |
| sourceMap | boolean | false | Use SourceMaps to map error message locations to modules. This slows down the compilation. **Important!** `cheap` source map options don't work with the plugin! |
| test | RegExp, Array<RegExp> | <code>/\.js($&#124;\?)/i</code> | Test to match files against. |
| include | RegExp, Array<RegExp> | | Test only `include` files. |
| exclude | RegExp, Array<RegExp> | | Files to `exclude` from testing. |
| warningsFilter | function(source) -> boolean | | Allow to filter uglify warnings (since webpack 2.3.0) |

<h2 align="center">Mangling</h2>

`mangle (boolean|object)` - Passing `true` or an object enables and provides options for UglifyJS name mangling. See [UglifyJS documentation](https://github.com/mishoo/UglifyJS2/tree/v2.x#mangle) for mangle options. Example configuration, this will **not** mangle properties (see below):

```javascript
new UglifyJsPlugin({
mangle: {
// Skip mangling these
except: ['$super', '$', 'exports', 'require']
}
})
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`test`**|`{RegExp\|Array<RegExp>}`| <code>/\.js($&#124;\?)/i</code>|Test to match files against|
|**`include`**|`{RegExp\|Array<RegExp>}`|`undefined`|Files to `include`|
|**`exclude`**|`{RegExp\|Array<RegExp>}`|`undefined`|Files to `exclude`|
|**`sourceMap`**|`{Boolean}`|`false`|Use SourceMaps to map error message locations to modules (This slows down the compilation) ⚠️ **`cheap-source-map` options don't work with this plugin**|
|**`uglifyOptions`**|`{Object}`|[`{}`](https://github.com/webpack-contrib/uglifyjs-webpack-plugin/tree/readme#uglifyoptions)|`uglify` [Options](https://github.com/mishoo/UglifyJS2/tree/master#minify-options)|
|**`extractComments`**|`{Boolean\|RegExp\|Function<(node, comment) -> {Boolean\|Object}>}`|`false`|Whether comments shall be extracted to a separate file, (see [details](https://github.com/webpack/webpack/commit/71933e979e51c533b432658d5e37917f9e71595a) (`webpack >= 2.3.0`)|
|**`warningsFilter`**|`{Function(source) -> {Boolean}}`|``|Allow to filter uglify warnings|

### `test`

**webpack.config.js**
```js
[
new UglifyJSPlugin({
test: /\.js($&#124;\?)/i
})
]
```

`mangle.props (boolean|object)` - Passing `true` or an object enables and provides options for UglifyJS property mangling - see [UglifyJS documentation](https://github.com/mishoo/UglifyJS2/tree/v2.x#mangleproperties-options) for mangleProperties options.
### `include`

> Note: the UglifyJS docs warn that [you will probably break your source if you use property mangling](https://github.com/mishoo/UglifyJS2/tree/v2.x#mangling-property-names---mangle-props), so if you aren’t sure why you’d need this feature, you most likely shouldn’t be using it! This is **not** enabled by default.
**webpack.config.js**
```js
[
new UglifyJSPlugin({
include: /\/includes/
})
]
```

Example configuration, this will mangle both names and properties:
### `exclude`

```javascript
new UglifyJsPlugin({
mangle: {
props: true
}
})
**webpack.config.js**
```js
[
new UglifyJSPlugin({
exclude: /\/excludes/
})
]
```

<h2 align="center">Extracting Comments</h2>
### `sourceMap`

**webpack.config.js**
```js
[
new UglifyJSPlugin({
sourceMap: true
})
]
```

> ⚠️ **`cheap-source-map` options don't work with this plugin**
### [`uglifyOptions`](https://github.com/mishoo/UglifyJS2/tree/master#minify-options)

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`ie8`**|`{Boolean}`|`false`|Enable IE8 Support|
|**[`parse`](https://github.com/mishoo/UglifyJS2/tree/master#parse-options)**|`{Object}`|`{}`|Additional Parse Options|
|**[`mangle`](https://github.com/mishoo/UglifyJS2/tree/master#mangle-options)**|`{Boolean\|Object}`|`true`|Enable Name Mangling (See [Mangle Properties](https://github.com/mishoo/UglifyJS2/tree/master#mangle-properties-options) for advanced setups, use with ⚠️)|
|**[`output`](https://github.com/mishoo/UglifyJS2/tree/master#output-options)**|`{Object}`|`{}`|Additional Output Options (The defaults are optimized for best compression)|
|**[`compress`](https://github.com/mishoo/UglifyJS2/tree/master#compress-options)**|`{Boolean\|Object}`|`true`|Additional Compress Options|
|**`warnings`**|`{Boolean}`|`false`|Display Warnings|

**webpack.config.js**
```js
[
new UglifyJSPlugin({
uglifyOptions: {
ie8: false,
parse: {...options},
mangle: {
...options,
properties: {
// mangle property options
}
},
output: {
comments: false,
beautify: false,
...options
},
compress: {...options},
warnings: false
}
})
]
```

### `extractComments`

The `extractComments` option can be

- `true`: All comments that normally would be preserved by the `comments` option will be moved to a separate file. If the original file is named `foo.js`, then the comments will be stored to `foo.js.LICENSE`
- regular expression (given as `RegExp` or `string`) or a `function (astNode, comment) -> boolean`:
All comments that match the given expression (resp. are evaluated to `true` by the function) will be extracted to the separate file. The `comments` option specifies whether the comment will be preserved, i.e. it is possible to preserve some comments (e.g. annotations) while extracting others or even preserving comments that have been extracted.
- an `object` consisting of the following keys, all optional:
- `condition`: regular expression or function (see previous point)
- `filename`: The file where the extracted comments will be stored. Can be either a `string` or `function (string) -> string` which will be given the original filename. Default is to append the suffix `.LICENSE` to the original filename.
- `banner`: The banner text that points to the extracted file and will be added on top of the original file. will be added to the original file. Can be `false` (no banner), a `string`, or a `function (string) -> string` that will be called with the filename where extracted comments have been stored. Will be wrapped into comment.

Default: `/*! For license information please see foo.js.LICENSE */`

### `warningsFilter`

**webpack.config.js**
```js
[
new UglifyJSPlugin({
warningsFilter: (src) => true
})
]
```

<h2 align="center">Maintainers</h2>

<table>
<tbody>
<tr>
<td align="center">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/166921?v=3&s=150">
</br>
<a href="https://github.com/bebraw">Juho Vepsäläinen</a>
<a href="https://github.com/TheLarkInn">
<img width="150" height="150" src="https://github.com/TheLarkInn.png?size=150">
</br>
Sean Larkin
</a>
</td>
<td align="center">
<img width="150" height="150"
src="https://avatars2.githubusercontent.com/u/8420490?v=3&s=150">
</br>
<a href="https://github.com/d3viant0ne">Joshua Wiens</a>
<a href="https://github.com/bebraw">
<img width="150" height="150" src="https://github.com/bebraw.png?v=3&s=150">
</br>
Juho Vepsäläinen
</a>
</td>
<td align="center">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/533616?v=3&s=150">
</br>
<a href="https://github.com/SpaceK33z">Kees Kluskens</a>
<a href="https://github.com/d3viant0ne">
<img width="150" height="150" src="https://github.com/d3viant0ne.png?v=3&s=150">
</br>
Joshua Wiens
</a>
</td>
<td align="center">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/3408176?v=3&s=150">
</br>
<a href="https://github.com/TheLarkInn">Sean Larkin</a>
<a href="https://github.com/michael-ciniawsky">
<img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
</br>
Michael Ciniawsky
</a>
</td>
<td align="center">
<a href="https://github.com/evilebottnawi">
<img width="150" height="150" src="https://github.com/evilebottnawi.png?v=3&s=150">
</br>
Alexander Krasnoyarov
</a>
</td>
</tr>
<tbody>
Expand All @@ -155,17 +203,17 @@ Default: `/*! For license information please see foo.js.LICENSE */`
[npm]: https://img.shields.io/npm/v/uglifyjs-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/uglifyjs-webpack-plugin

[node]: https://img.shields.io/node/v/uglifyjs-webpack-plugin.svg
[node-url]: https://nodejs.org

[deps]: https://david-dm.org/webpack-contrib/uglifyjs-webpack-plugin.svg
[deps-url]: https://david-dm.org/webpack-contrib/uglifyjs-webpack-plugin

[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack

[test]: https://secure.travis-ci.org/webpack-contrib/uglifyjs-webpack-plugin.svg
[test-url]: http://travis-ci.org/webpack-contrib/uglifyjs-webpack-plugin

[cover]: https://codecov.io/gh/webpack-contrib/uglifyjs-webpack-plugin/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/uglifyjs-webpack-plugin

[quality]: https://www.bithound.io/github/webpack-contrib/uglifyjs-webpack-plugin/badges/score.svg
[quality-url]: https://www.bithound.io/github/webpack-contrib/uglifyjs-webpack-plugin
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack

0 comments on commit 9268e30

Please sign in to comment.