diff options
Diffstat (limited to 'node_modules/uglifyjs-webpack-plugin/README.md')
| -rw-r--r-- | node_modules/uglifyjs-webpack-plugin/README.md | 462 |
1 files changed, 362 insertions, 100 deletions
diff --git a/node_modules/uglifyjs-webpack-plugin/README.md b/node_modules/uglifyjs-webpack-plugin/README.md index f5713fd1b..a8147638c 100644 --- a/node_modules/uglifyjs-webpack-plugin/README.md +++ b/node_modules/uglifyjs-webpack-plugin/README.md @@ -1,123 +1,374 @@ [![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/harmony">UglifyJS v3 </a><a href="https://npmjs.com/package/uglify-es">(`uglify-es`)</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 < v4.0.0` currently contains [`v0.4.6`](https://github.com/webpack-contrib/uglifyjs-webpack-plugin/tree/version-0.4) of this plugin under `webpack.optimize.UglifyJsPlugin` as an alias. For usage of the latest version (`v1.0.0`), please follow the instructions below. Aliasing `v1.0.0` as `webpack.optimize.UglifyJsPlugin` is scheduled for `webpack v4.0.0` <h2 align="center">Install</h2> -With [Yarn](https://yarnpkg.com): - ```bash -yarn add uglifyjs-webpack-plugin --dev +npm i -D uglifyjs-webpack-plugin ``` -With npm: +<h2 align="center">Usage</h2> -```bash -npm install uglifyjs-webpack-plugin --save-dev +**webpack.config.js** +```js +const UglifyJsPlugin = require('uglifyjs-webpack-plugin') + +module.exports = { + //... + optimization: { + minimizer: [ + new UglifyJsPlugin() + ] + } +} ``` -**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. +<h2 align="center">Options</h2> + +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|**`test`**|`{RegExp\|Array<RegExp>}`| <code>/\\.js$/i</code>|Test to match files against| +|**`include`**|`{RegExp\|Array<RegExp>}`|`undefined`|Files to `include`| +|**`exclude`**|`{RegExp\|Array<RegExp>}`|`undefined`|Files to `exclude`| +|**`cache`**|`{Boolean\|String}`|`false`|Enable file caching| +|**`cacheKeys`**|`{Function(defaultCacheKeys, file) -> {Object}}`|`defaultCacheKeys => defaultCacheKeys`|Allows you to override default cache keys| +|**`parallel`**|`{Boolean\|Number}`|`false`|Use multi-process parallel running to improve the build speed| +|**`sourceMap`**|`{Boolean}`|`false`|Use source maps to map error message locations to modules (This slows down the compilation) ⚠️ **`cheap-source-map` options don't work with this plugin**| +|**`minify`**|`{Function}`|`undefined`|Allows you to override default minify function| +|**`uglifyOptions`**|`{Object}`|[`{...defaults}`](https://github.com/webpack-contrib/uglifyjs-webpack-plugin/tree/master#uglifyoptions)|`uglify` [Options](https://github.com/mishoo/UglifyJS2/tree/harmony#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}}`|`() => true`|Allow to filter uglify warnings| + +### `test` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + test: /\.js($|\?)/i + }) +] +``` -If your minification target is ES6: +### `include` -```bash -yarn add git://github.com/mishoo/UglifyJS2#harmony-v2.8.22 --dev +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + include: /\/includes/ + }) +] ``` -If your minification target is ES5: +### `exclude` -```bash -yarn add uglify-js --dev +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + exclude: /\/excludes/ + }) +] ``` -<h2 align="center">Usage</h2> +### `cache` -```javascript -const UglifyJSPlugin = require('uglifyjs-webpack-plugin'); +If you use your own `minify` function please read the `minify` section for cache invalidation correctly. -module.exports = { - entry: {...}, - output: {...}, - module: {...}, - plugins: [ - new UglifyJSPlugin() - ] -}; +#### `{Boolean}` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + cache: true + }) +] ``` -<h2 align="center">Options</h2> +Enable file caching. +Default path to cache directory: `node_modules/.cache/uglifyjs-webpack-plugin`. -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 below. | -| 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($|\?)/i</code> | Test to match files against. | -| include | RegExp, Array<RegExp> | | Test only `include` files. | -| exclude | RegExp, Array<RegExp> | | Files to `exclude` from testing. | -| extractComments | boolean, RegExp, object | | Extract comments to separate file (see [details](https://github.com/webpack/webpack/commit/71933e979e51c533b432658d5e37917f9e71595a), since webpack 2.3.0) | -| 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'] - } -}) +#### `{String}` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + cache: 'path/to/cache' + }) +] ``` -`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. +Path to cache directory. + +### `cacheKeys` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + cache: true, + cacheKeys: (defaultCacheKeys, file) => { + defaultCacheKeys.myCacheKey = 'myCacheKeyValue'; + + return defaultCacheKeys; + }, + }) +] +``` -> 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. +Allows you to override default cache keys. + +Default keys: +```js +{ + 'uglify-es': versions.uglify, // uglify version + 'uglifyjs-webpack-plugin': versions.plugin, // plugin version + 'uglifyjs-webpack-plugin-options': this.options, // plugin options + path: compiler.outputPath ? `${compiler.outputPath}/${file}` : file, // asset path + hash: crypto.createHash('md4').update(input).digest('hex'), // source file hash +} +``` -Example configuration, this will mangle both names and properties: +### `parallel` -```javascript -new UglifyJsPlugin({ - mangle: { - props: true - } -}) +#### `{Boolean}` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + parallel: true + }) +] +``` + +Enable parallelization. +Default number of concurrent runs: `os.cpus().length - 1`. + +#### `{Number}` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + parallel: 4 + }) +] +``` + +Number of concurrent runs. + +> ℹ️ Parallelization can speedup your build significantly and is therefore **highly recommended** + +### `sourceMap` + +If you use your own `minify` function please read the `minify` section for handling source maps correctly. + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + sourceMap: true + }) +] +``` + +> ⚠️ **`cheap-source-map` options don't work with this plugin** + +### `minify` + +> ⚠️ **Always use `require` inside `minify` function when `parallel` option enabled** + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + minify(file, sourceMap) { + const extractedComments = []; + + // Custom logic for extract comments + + const { error, map, code, warnings } = require('uglify-module') // Or require('./path/to/uglify-module') + .minify( + file, + { /* Your options for minification */ }, + ); + + return { error, map, code, warnings, extractedComments }; + } + }) +] +``` + +By default plugin uses `uglify-es` package. + +Examples: + +#### `uglify-js` + +```bash +npm i -D uglify-js +``` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + // Uncomment lines below for cache invalidation correctly + // cache: true, + // cacheKeys(defaultCacheKeys) { + // return Object.assign( + // {}, + // defaultCacheKeys, + // { 'uglify-js': require('uglify-js/package.json').version }, + // ); + // }, + minify(file, sourceMap) { + // https://github.com/mishoo/UglifyJS2#minify-options + const uglifyJsOptions = { /* your `uglify-js` package options */ }; + + if (sourceMap) { + uglifyJsOptions.sourceMap = { + content: sourceMap, + }; + } + + return require('uglify-js').minify(file, uglifyJsOptions); + } + }) +] ``` -<h2 align="center">Extracting Comments</h2> +#### `terser` -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 */` +```bash +npm i -D terser +``` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + // Uncomment lines below for cache invalidation correctly + // cache: true, + // cacheKeys(defaultCacheKeys) { + // return Object.assign( + // {}, + // defaultCacheKeys, + // { terser: require('terser/package.json').version }, + // ); + // }, + minify(file, sourceMap) { + // https://github.com/fabiosantoscode/terser#minify-options + const terserOptions = { /* your `terser` package options */ }; + + if (sourceMap) { + terserOption.sourceMap = { + content: sourceMap, + }; + } + + return require('terser').minify(file, terserOptions); + } + }) +] +``` + +### [`uglifyOptions`](https://github.com/mishoo/UglifyJS2/tree/harmony#minify-options) + +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|**`ecma`**|`{Number}`|`undefined`|Supported ECMAScript Version (`5`, `6`, `7` or `8`). Affects `parse`, `compress` && `output` options| +|**`warnings`**|`{Boolean}`|`false`|Display Warnings| +|**[`parse`](https://github.com/mishoo/UglifyJS2/tree/harmony#parse-options)**|`{Object}`|`{}`|Additional Parse Options| +|**[`compress`](https://github.com/mishoo/UglifyJS2/tree/harmony#compress-options)**|`{Boolean\|Object}`|`true`|Additional Compress Options| +|**[`mangle`](https://github.com/mishoo/UglifyJS2/tree/harmony#mangle-options)**|`{Boolean\|Object}`|`{inline: false}`|Enable Name Mangling (See [Mangle Properties](https://github.com/mishoo/UglifyJS2/tree/harmony#mangle-properties-options) for advanced setups, use with ⚠️)| +|**[`output`](https://github.com/mishoo/UglifyJS2/tree/harmony#output-options)**|`{Object}`|`{comments: extractComments ? false : /^\**!\|@preserve\|@license\|@cc_on/,}`|Additional Output Options (The defaults are optimized for best compression)| +|**`toplevel`**|`{Boolean}`|`false`|Enable top level variable and function name mangling and to drop unused variables and functions| +|**`nameCache`**|`{Object}`|`null`|Enable cache of mangled variable and property names across multiple invocations| +|**`ie8`**|`{Boolean}`|`false`|Enable IE8 Support| +|**`keep_classnames`**|`{Boolean}`|`undefined`|Enable prevent discarding or mangling of class names| +|**`keep_fnames`**|`{Boolean}`|`false`| Enable prevent discarding or mangling of function names. Useful for code relying on `Function.prototype.name`. If the top level minify option `keep_classnames` is `undefined` it will be overriden with the value of the top level minify option `keep_fnames`| +|**`safari10`**|`{Boolean}`|`false`|Enable work around Safari 10/11 bugs in loop scoping and `await`| + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + uglifyOptions: { + ecma: 8, + warnings: false, + parse: {...options}, + compress: {...options}, + mangle: { + ...options, + properties: { + // mangle property options + } + }, + output: { + comments: false, + beautify: false, + ...options + }, + toplevel: false, + nameCache: null, + ie8: false, + keep_classnames: undefined, + keep_fnames: false, + safari10: false, + } + }) +] +``` +### `extractComments` + +#### `{Boolean}` + +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`. + +#### `{RegExp|String}` or `{Function<(node, 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. + +#### `{Object}` + +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|**`condition`**|`{Regex\|Function}`|``|Regular Expression or function (see previous point)| +|**`filename`**|`{String\|Function}`|`${file}.LICENSE`|The file where the extracted comments will be stored. Can be either a `{String}` or a `{Function<(string) -> {String}>}`, which will be given the original filename. Default is to append the suffix `.LICENSE` to the original filename| +|**`banner`**|`{Boolean\|String\|Function}`|`/*! For license information please see ${filename}.js.LICENSE */`|The banner text that points to the extracted file and will be added on top of 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| + +### `warningsFilter` + +**webpack.config.js** +```js +[ + new UglifyJsPlugin({ + warningsFilter: (src) => true + }) +] +``` <h2 align="center">Maintainers</h2> @@ -125,28 +376,39 @@ Default: `/*! For license information please see foo.js.LICENSE */` <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/hulkish"> + <img width="150" height="150" src="https://github.com/hulkish.png?size=150"> + </br> + Steven Hargrove + </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> @@ -156,17 +418,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 +[test]: https://img.shields.io/circleci/project/github/webpack-contrib/uglifyjs-webpack-plugin.svg +[test-url]: https://circleci.com/gh/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 |