996 lines
41 KiB
Markdown
996 lines
41 KiB
Markdown
UglifyJS 2
|
||
==========
|
||
[](https://travis-ci.org/mishoo/UglifyJS2)
|
||
|
||
UglifyJS is a JavaScript parser, minifier, compressor or beautifier toolkit.
|
||
|
||
This page documents the command line utility. For
|
||
[API and internals documentation see my website](http://lisperator.net/uglifyjs/).
|
||
There's also an
|
||
[in-browser online demo](http://lisperator.net/uglifyjs/#demo) (for Firefox,
|
||
Chrome and probably Safari).
|
||
|
||
#### Note:
|
||
- `uglify-js` only supports ECMAScript 5 (ES5).
|
||
- Support for `const` is [present but incomplete](#support-for-const), and may not be
|
||
transformed properly.
|
||
- Those wishing to minify ES2015+ (ES6+) should use the `npm` package [**uglify-es**](https://github.com/mishoo/UglifyJS2/tree/harmony).
|
||
|
||
Install
|
||
-------
|
||
|
||
First make sure you have installed the latest version of [node.js](http://nodejs.org/)
|
||
(You may need to restart your computer after this step).
|
||
|
||
From NPM for use as a command line app:
|
||
|
||
npm install uglify-js -g
|
||
|
||
From NPM for programmatic use:
|
||
|
||
npm install uglify-js
|
||
|
||
Usage
|
||
-----
|
||
|
||
uglifyjs [input files] [options]
|
||
|
||
UglifyJS2 can take multiple input files. It's recommended that you pass the
|
||
input files first, then pass the options. UglifyJS will parse input files
|
||
in sequence and apply any compression options. The files are parsed in the
|
||
same global scope, that is, a reference from a file to some
|
||
variable/function declared in another file will be matched properly.
|
||
|
||
If you want to read from STDIN instead, pass a single dash instead of input
|
||
files.
|
||
|
||
If you wish to pass your options before the input files, separate the two with
|
||
a double dash to prevent input files being used as option arguments:
|
||
|
||
uglifyjs --compress --mangle -- input.js
|
||
|
||
The available options are:
|
||
|
||
```
|
||
--source-map Specify an output file where to generate source
|
||
map.
|
||
--source-map-root The path to the original source to be included
|
||
in the source map.
|
||
--source-map-url The path to the source map to be added in //#
|
||
sourceMappingURL. Defaults to the value passed
|
||
with --source-map.
|
||
--source-map-include-sources Pass this flag if you want to include the
|
||
content of source files in the source map as
|
||
sourcesContent property.
|
||
--source-map-inline Write base64-encoded source map to the end of js output.
|
||
--in-source-map Input source map, useful if you're compressing
|
||
JS that was generated from some other original
|
||
code. Specify "inline" if the source map is included
|
||
inline with the sources.
|
||
--screw-ie8 Use this flag if you don't wish to support
|
||
Internet Explorer 6/7/8.
|
||
By default UglifyJS will not try to be IE-proof.
|
||
--support-ie8 Use this flag to support Internet Explorer 6/7/8.
|
||
Equivalent to setting `screw_ie8: false` in `minify()`
|
||
for `compress`, `mangle` and `output` options.
|
||
--expr Parse a single expression, rather than a
|
||
program (for parsing JSON)
|
||
-p, --prefix Skip prefix for original filenames that appear
|
||
in source maps. For example -p 3 will drop 3
|
||
directories from file names and ensure they are
|
||
relative paths. You can also specify -p
|
||
relative, which will make UglifyJS figure out
|
||
itself the relative paths between original
|
||
sources, the source map and the output file.
|
||
-o, --output Output file (default STDOUT).
|
||
-b, --beautify Beautify output/specify output options.
|
||
-m, --mangle Mangle names/pass mangler options.
|
||
-r, --reserved Reserved names to exclude from mangling.
|
||
-c, --compress Enable compressor/pass compressor options, e.g.
|
||
`-c 'if_return=false,pure_funcs=["Math.pow","console.log"]'`
|
||
Use `-c` with no argument to enable default compression
|
||
options.
|
||
-d, --define Global definitions
|
||
-e, --enclose Embed everything in a big function, with a
|
||
configurable parameter/argument list.
|
||
--comments Preserve copyright comments in the output. By
|
||
default this works like Google Closure, keeping
|
||
JSDoc-style comments that contain "@license" or
|
||
"@preserve". You can optionally pass one of the
|
||
following arguments to this flag:
|
||
- "all" to keep all comments
|
||
- a valid JS RegExp like `/foo/` or `/^!/` to
|
||
keep only matching comments.
|
||
Note that currently not *all* comments can be
|
||
kept when compression is on, because of dead
|
||
code removal or cascading statements into
|
||
sequences.
|
||
--preamble Preamble to prepend to the output. You can use
|
||
this to insert a comment, for example for
|
||
licensing information. This will not be
|
||
parsed, but the source map will adjust for its
|
||
presence.
|
||
--stats Display operations run time on STDERR.
|
||
--acorn Use Acorn for parsing.
|
||
--spidermonkey Assume input files are SpiderMonkey AST format
|
||
(as JSON).
|
||
--self Build itself (UglifyJS2) as a library (implies
|
||
--wrap=UglifyJS --export-all)
|
||
--wrap Embed everything in a big function, making the
|
||
“exports” and “global” variables available. You
|
||
need to pass an argument to this option to
|
||
specify the name that your module will take
|
||
when included in, say, a browser.
|
||
--export-all Only used when --wrap, this tells UglifyJS to
|
||
add code to automatically export all globals.
|
||
--lint Display some scope warnings
|
||
-v, --verbose Verbose
|
||
-V, --version Print version number and exit.
|
||
--noerr Don't throw an error for unknown options in -c,
|
||
-b or -m.
|
||
--bare-returns Allow return outside of functions. Useful when
|
||
minifying CommonJS modules and Userscripts that
|
||
may be anonymous function wrapped (IIFE) by the
|
||
.user.js engine `caller`.
|
||
--keep-fnames Do not mangle/drop function names. Useful for
|
||
code relying on Function.prototype.name.
|
||
--reserved-file File containing reserved names
|
||
--reserve-domprops Make (most?) DOM properties reserved for
|
||
--mangle-props
|
||
--mangle-props Mangle property names (default `0`). Set to
|
||
`true` or `1` to mangle all property names. Set
|
||
to `unquoted` or `2` to only mangle unquoted
|
||
property names. Mode `2` also enables the
|
||
`keep_quoted_props` beautifier option to
|
||
preserve the quotes around property names and
|
||
disables the `properties` compressor option to
|
||
prevent rewriting quoted properties with dot
|
||
notation. You can override these by setting
|
||
them explicitly on the command line.
|
||
--mangle-regex Only mangle property names matching the regex
|
||
--name-cache File to hold mangled names mappings
|
||
--pure-funcs Functions that can be safely removed if their
|
||
return value is not used, e.g.
|
||
`--pure-funcs Math.floor console.info`
|
||
(requires `--compress`)
|
||
```
|
||
|
||
Specify `--output` (`-o`) to declare the output file. Otherwise the output
|
||
goes to STDOUT.
|
||
|
||
## Source map options
|
||
|
||
UglifyJS2 can generate a source map file, which is highly useful for
|
||
debugging your compressed JavaScript. To get a source map, pass
|
||
`--source-map output.js.map` (full path to the file where you want the
|
||
source map dumped).
|
||
|
||
Additionally you might need `--source-map-root` to pass the URL where the
|
||
original files can be found. In case you are passing full paths to input
|
||
files to UglifyJS, you can use `--prefix` (`-p`) to specify the number of
|
||
directories to drop from the path prefix when declaring files in the source
|
||
map.
|
||
|
||
For example:
|
||
|
||
uglifyjs /home/doe/work/foo/src/js/file1.js \
|
||
/home/doe/work/foo/src/js/file2.js \
|
||
-o foo.min.js \
|
||
--source-map foo.min.js.map \
|
||
--source-map-root http://foo.com/src \
|
||
-p 5 -c -m
|
||
|
||
The above will compress and mangle `file1.js` and `file2.js`, will drop the
|
||
output in `foo.min.js` and the source map in `foo.min.js.map`. The source
|
||
mapping will refer to `http://foo.com/src/js/file1.js` and
|
||
`http://foo.com/src/js/file2.js` (in fact it will list `http://foo.com/src`
|
||
as the source map root, and the original files as `js/file1.js` and
|
||
`js/file2.js`).
|
||
|
||
### Composed source map
|
||
|
||
When you're compressing JS code that was output by a compiler such as
|
||
CoffeeScript, mapping to the JS code won't be too helpful. Instead, you'd
|
||
like to map back to the original code (i.e. CoffeeScript). UglifyJS has an
|
||
option to take an input source map. Assuming you have a mapping from
|
||
CoffeeScript → compiled JS, UglifyJS can generate a map from CoffeeScript →
|
||
compressed JS by mapping every token in the compiled JS to its original
|
||
location.
|
||
|
||
To use this feature you need to pass `--in-source-map
|
||
/path/to/input/source.map` or `--in-source-map inline` if the source map is
|
||
included inline with the sources. Normally the input source map should also
|
||
point to the file containing the generated JS, so if that's correct you can
|
||
omit input files from the command line.
|
||
|
||
## Mangler options
|
||
|
||
To enable the mangler you need to pass `--mangle` (`-m`). The following
|
||
(comma-separated) options are supported:
|
||
|
||
- `toplevel` — mangle names declared in the toplevel scope (disabled by
|
||
default).
|
||
|
||
- `eval` — mangle names visible in scopes where `eval` or `with` are used
|
||
(disabled by default).
|
||
|
||
When mangling is enabled but you want to prevent certain names from being
|
||
mangled, you can declare those names with `--reserved` (`-r`) — pass a
|
||
comma-separated list of names. For example:
|
||
|
||
uglifyjs ... -m -r '$,require,exports'
|
||
|
||
to prevent the `require`, `exports` and `$` names from being changed.
|
||
|
||
### Mangling property names (`--mangle-props`)
|
||
|
||
**Note:** this will probably break your code. Mangling property names is a
|
||
separate step, different from variable name mangling. Pass
|
||
`--mangle-props`. It will mangle all properties that are seen in some
|
||
object literal, or that are assigned to. For example:
|
||
|
||
```js
|
||
var x = {
|
||
foo: 1
|
||
};
|
||
|
||
x.bar = 2;
|
||
x["baz"] = 3;
|
||
x[condition ? "moo" : "boo"] = 4;
|
||
console.log(x.something());
|
||
```
|
||
|
||
In the above code, `foo`, `bar`, `baz`, `moo` and `boo` will be replaced
|
||
with single characters, while `something()` will be left as is.
|
||
|
||
In order for this to be of any use, we should avoid mangling standard JS
|
||
names. For instance, if your code would contain `x.length = 10`, then
|
||
`length` becomes a candidate for mangling and it will be mangled throughout
|
||
the code, regardless if it's being used as part of your own objects or
|
||
accessing an array's length. To avoid that, you can use `--reserved-file`
|
||
to pass a filename that should contain the names to be excluded from
|
||
mangling. This file can be used both for excluding variable names and
|
||
property names. It could look like this, for example:
|
||
|
||
```js
|
||
{
|
||
"vars": [ "define", "require", ... ],
|
||
"props": [ "length", "prototype", ... ]
|
||
}
|
||
```
|
||
|
||
`--reserved-file` can be an array of file names (either a single
|
||
comma-separated argument, or you can pass multiple `--reserved-file`
|
||
arguments) — in this case it will exclude names from all those files.
|
||
|
||
A default exclusion file is provided in `tools/domprops.json` which should
|
||
cover most standard JS and DOM properties defined in various browsers. Pass
|
||
`--reserve-domprops` to read that in.
|
||
|
||
You can also use a regular expression to define which property names should be
|
||
mangled. For example, `--mangle-regex="/^_/"` will only mangle property names
|
||
that start with an underscore.
|
||
|
||
When you compress multiple files using this option, in order for them to
|
||
work together in the end we need to ensure somehow that one property gets
|
||
mangled to the same name in all of them. For this, pass `--name-cache
|
||
filename.json` and UglifyJS will maintain these mappings in a file which can
|
||
then be reused. It should be initially empty. Example:
|
||
|
||
```
|
||
rm -f /tmp/cache.json # start fresh
|
||
uglifyjs file1.js file2.js --mangle-props --name-cache /tmp/cache.json -o part1.js
|
||
uglifyjs file3.js file4.js --mangle-props --name-cache /tmp/cache.json -o part2.js
|
||
```
|
||
|
||
Now, `part1.js` and `part2.js` will be consistent with each other in terms
|
||
of mangled property names.
|
||
|
||
Using the name cache is not necessary if you compress all your files in a
|
||
single call to UglifyJS.
|
||
|
||
#### Mangling unquoted names (`--mangle-props=unquoted` or `--mangle-props=2`)
|
||
|
||
Using quoted property name (`o["foo"]`) reserves the property name (`foo`)
|
||
so that it is not mangled throughout the entire script even when used in an
|
||
unquoted style (`o.foo`). Example:
|
||
|
||
```
|
||
$ echo 'var o={"foo":1, bar:3}; o.foo += o.bar; console.log(o.foo);' | uglifyjs --mangle-props=2 -mc
|
||
var o={"foo":1,a:3};o.foo+=o.a,console.log(o.foo);
|
||
```
|
||
|
||
#### Debugging property name mangling
|
||
|
||
You can also pass `--mangle-props-debug` in order to mangle property names
|
||
without completely obscuring them. For example the property `o.foo`
|
||
would mangle to `o._$foo$_` with this option. This allows property mangling
|
||
of a large codebase while still being able to debug the code and identify
|
||
where mangling is breaking things.
|
||
|
||
You can also pass a custom suffix using `--mangle-props-debug=XYZ`. This would then
|
||
mangle `o.foo` to `o._$foo$XYZ_`. You can change this each time you compile a
|
||
script to identify how a property got mangled. One technique is to pass a
|
||
random number on every compile to simulate mangling changing with different
|
||
inputs (e.g. as you update the input script with new properties), and to help
|
||
identify mistakes like writing mangled keys to storage.
|
||
|
||
## Compressor options
|
||
|
||
You need to pass `--compress` (`-c`) to enable the compressor. Optionally
|
||
you can pass a comma-separated list of options. Options are in the form
|
||
`foo=bar`, or just `foo` (the latter implies a boolean option that you want
|
||
to set `true`; it's effectively a shortcut for `foo=true`).
|
||
|
||
- `sequences` (default: true) -- join consecutive simple statements using the
|
||
comma operator. May be set to a positive integer to specify the maximum number
|
||
of consecutive comma sequences that will be generated. If this option is set to
|
||
`true` then the default `sequences` limit is `200`. Set option to `false` or `0`
|
||
to disable. The smallest `sequences` length is `2`. A `sequences` value of `1`
|
||
is grandfathered to be equivalent to `true` and as such means `200`. On rare
|
||
occasions the default sequences limit leads to very slow compress times in which
|
||
case a value of `20` or less is recommended.
|
||
|
||
- `properties` -- rewrite property access using the dot notation, for
|
||
example `foo["bar"] → foo.bar`
|
||
|
||
- `dead_code` -- remove unreachable code
|
||
|
||
- `drop_debugger` -- remove `debugger;` statements
|
||
|
||
- `unsafe` (default: false) -- apply "unsafe" transformations (discussion below)
|
||
|
||
- `unsafe_comps` (default: false) -- Reverse `<` and `<=` to `>` and `>=` to
|
||
allow improved compression. This might be unsafe when an at least one of two
|
||
operands is an object with computed values due the use of methods like `get`,
|
||
or `valueOf`. This could cause change in execution order after operands in the
|
||
comparison are switching. Compression only works if both `comparisons` and
|
||
`unsafe_comps` are both set to true.
|
||
|
||
- `unsafe_math` (default: false) -- optimize numerical expressions like
|
||
`2 * x * 3` into `6 * x`, which may give imprecise floating point results.
|
||
|
||
- `unsafe_proto` (default: false) -- optimize expressions like
|
||
`Array.prototype.slice.call(a)` into `[].slice.call(a)`
|
||
|
||
- `unsafe_regexp` (default: false) -- enable substitutions of variables with
|
||
`RegExp` values the same way as if they are constants.
|
||
|
||
- `conditionals` -- apply optimizations for `if`-s and conditional
|
||
expressions
|
||
|
||
- `comparisons` -- apply certain optimizations to binary nodes, for example:
|
||
`!(a <= b) → a > b` (only when `unsafe_comps`), attempts to negate binary
|
||
nodes, e.g. `a = !b && !c && !d && !e → a=!(b||c||d||e)` etc.
|
||
|
||
- `evaluate` -- attempt to evaluate constant expressions
|
||
|
||
- `booleans` -- various optimizations for boolean context, for example `!!a
|
||
? b : c → a ? b : c`
|
||
|
||
- `loops` -- optimizations for `do`, `while` and `for` loops when we can
|
||
statically determine the condition
|
||
|
||
- `unused` -- drop unreferenced functions and variables (simple direct variable
|
||
assignments do not count as references unless set to `"keep_assign"`)
|
||
|
||
- `toplevel` -- drop unreferenced functions (`"funcs"`) and/or variables (`"vars"`)
|
||
in the toplevel scope (`false` by default, `true` to drop both unreferenced
|
||
functions and variables)
|
||
|
||
- `top_retain` -- prevent specific toplevel functions and variables from `unused`
|
||
removal (can be array, comma-separated, RegExp or function. Implies `toplevel`)
|
||
|
||
- `hoist_funs` -- hoist function declarations
|
||
|
||
- `hoist_vars` (default: false) -- hoist `var` declarations (this is `false`
|
||
by default because it seems to increase the size of the output in general)
|
||
|
||
- `if_return` -- optimizations for if/return and if/continue
|
||
|
||
- `join_vars` -- join consecutive `var` statements
|
||
|
||
- `cascade` -- small optimization for sequences, transform `x, x` into `x`
|
||
and `x = something(), x` into `x = something()`
|
||
|
||
- `collapse_vars` -- Collapse single-use `var` and `const` definitions
|
||
when possible.
|
||
|
||
- `reduce_vars` -- Improve optimization on variables assigned with and
|
||
used as constant values.
|
||
|
||
- `warnings` -- display warnings when dropping unreachable code or unused
|
||
declarations etc.
|
||
|
||
- `negate_iife` -- negate "Immediately-Called Function Expressions"
|
||
where the return value is discarded, to avoid the parens that the
|
||
code generator would insert.
|
||
|
||
- `pure_getters` -- the default is `false`. If you pass `true` for
|
||
this, UglifyJS will assume that object property access
|
||
(e.g. `foo.bar` or `foo["bar"]`) doesn't have any side effects.
|
||
Specify `"strict"` to treat `foo.bar` as side-effect-free only when
|
||
`foo` is certain to not throw, i.e. not `null` or `undefined`.
|
||
|
||
- `pure_funcs` -- default `null`. You can pass an array of names and
|
||
UglifyJS will assume that those functions do not produce side
|
||
effects. DANGER: will not check if the name is redefined in scope.
|
||
An example case here, for instance `var q = Math.floor(a/b)`. If
|
||
variable `q` is not used elsewhere, UglifyJS will drop it, but will
|
||
still keep the `Math.floor(a/b)`, not knowing what it does. You can
|
||
pass `pure_funcs: [ 'Math.floor' ]` to let it know that this
|
||
function won't produce any side effect, in which case the whole
|
||
statement would get discarded. The current implementation adds some
|
||
overhead (compression will be slower).
|
||
|
||
- `drop_console` -- default `false`. Pass `true` to discard calls to
|
||
`console.*` functions. If you wish to drop a specific function call
|
||
such as `console.info` and/or retain side effects from function arguments
|
||
after dropping the function call then use `pure_funcs` instead.
|
||
|
||
- `expression` -- default `false`. Pass `true` to preserve completion values
|
||
from terminal statements without `return`, e.g. in bookmarklets.
|
||
|
||
- `keep_fargs` -- default `true`. Prevents the
|
||
compressor from discarding unused function arguments. You need this
|
||
for code which relies on `Function.length`.
|
||
|
||
- `keep_fnames` -- default `false`. Pass `true` to prevent the
|
||
compressor from discarding function names. Useful for code relying on
|
||
`Function.prototype.name`. See also: the `keep_fnames` [mangle option](#mangle).
|
||
|
||
- `passes` -- default `1`. Number of times to run compress with a maximum of 3.
|
||
In some cases more than one pass leads to further compressed code. Keep in
|
||
mind more passes will take more time.
|
||
|
||
- `keep_infinity` -- default `false`. Pass `true` to prevent `Infinity` from
|
||
being compressed into `1/0`, which may cause performance issues on Chrome.
|
||
|
||
- `side_effects` -- default `true`. Pass `false` to disable potentially dropping
|
||
functions marked as "pure". A function call is marked as "pure" if a comment
|
||
annotation `/*@__PURE__*/` or `/*#__PURE__*/` immediately precedes the call. For
|
||
example: `/*@__PURE__*/foo();`
|
||
|
||
|
||
### The `unsafe` option
|
||
|
||
It enables some transformations that *might* break code logic in certain
|
||
contrived cases, but should be fine for most code. You might want to try it
|
||
on your own code, it should reduce the minified size. Here's what happens
|
||
when this flag is on:
|
||
|
||
- `new Array(1, 2, 3)` or `Array(1, 2, 3)` → `[ 1, 2, 3 ]`
|
||
- `new Object()` → `{}`
|
||
- `String(exp)` or `exp.toString()` → `"" + exp`
|
||
- `new Object/RegExp/Function/Error/Array (...)` → we discard the `new`
|
||
- `typeof foo == "undefined"` → `foo === void 0`
|
||
- `void 0` → `undefined` (if there is a variable named "undefined" in
|
||
scope; we do it because the variable name will be mangled, typically
|
||
reduced to a single character)
|
||
|
||
### Conditional compilation
|
||
|
||
You can use the `--define` (`-d`) switch in order to declare global
|
||
variables that UglifyJS will assume to be constants (unless defined in
|
||
scope). For example if you pass `--define DEBUG=false` then, coupled with
|
||
dead code removal UglifyJS will discard the following from the output:
|
||
```javascript
|
||
if (DEBUG) {
|
||
console.log("debug stuff");
|
||
}
|
||
```
|
||
|
||
You can specify nested constants in the form of `--define env.DEBUG=false`.
|
||
|
||
UglifyJS will warn about the condition being always false and about dropping
|
||
unreachable code; for now there is no option to turn off only this specific
|
||
warning, you can pass `warnings=false` to turn off *all* warnings.
|
||
|
||
Another way of doing that is to declare your globals as constants in a
|
||
separate file and include it into the build. For example you can have a
|
||
`build/defines.js` file with the following:
|
||
```javascript
|
||
const DEBUG = false;
|
||
const PRODUCTION = true;
|
||
// etc.
|
||
```
|
||
|
||
and build your code like this:
|
||
|
||
uglifyjs build/defines.js js/foo.js js/bar.js... -c
|
||
|
||
UglifyJS will notice the constants and, since they cannot be altered, it
|
||
will evaluate references to them to the value itself and drop unreachable
|
||
code as usual. The build will contain the `const` declarations if you use
|
||
them. If you are targeting < ES6 environments which does not support `const`,
|
||
using `var` with `reduce_vars` (enabled by default) should suffice.
|
||
|
||
<a name="codegen-options"></a>
|
||
|
||
#### Conditional compilation, API
|
||
You can also use conditional compilation via the programmatic API. With the difference that the
|
||
property name is `global_defs` and is a compressor property:
|
||
|
||
```js
|
||
uglifyJS.minify([ "input.js"], {
|
||
compress: {
|
||
dead_code: true,
|
||
global_defs: {
|
||
DEBUG: false
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
## Beautifier options
|
||
|
||
The code generator tries to output shortest code possible by default. In
|
||
case you want beautified output, pass `--beautify` (`-b`). Optionally you
|
||
can pass additional arguments that control the code output:
|
||
|
||
- `beautify` (default `true`) -- whether to actually beautify the output.
|
||
Passing `-b` will set this to true, but you might need to pass `-b` even
|
||
when you want to generate minified code, in order to specify additional
|
||
arguments, so you can use `-b beautify=false` to override it.
|
||
- `indent-level` (default 4)
|
||
- `indent-start` (default 0) -- prefix all lines by that many spaces
|
||
- `quote-keys` (default `false`) -- pass `true` to quote all keys in literal
|
||
objects
|
||
- `space-colon` (default `true`) -- insert a space after the colon signs
|
||
- `ascii-only` (default `false`) -- escape Unicode characters in strings and
|
||
regexps (affects directives with non-ascii characters becoming invalid)
|
||
- `inline-script` (default `false`) -- escape the slash in occurrences of
|
||
`</script` in strings
|
||
- `width` (default 80) -- only takes effect when beautification is on, this
|
||
specifies an (orientative) line width that the beautifier will try to
|
||
obey. It refers to the width of the line text (excluding indentation).
|
||
It doesn't work very well currently, but it does make the code generated
|
||
by UglifyJS more readable.
|
||
- `max-line-len` (default 32000) -- maximum line length (for uglified code)
|
||
- `bracketize` (default `false`) -- always insert brackets in `if`, `for`,
|
||
`do`, `while` or `with` statements, even if their body is a single
|
||
statement.
|
||
- `semicolons` (default `true`) -- separate statements with semicolons. If
|
||
you pass `false` then whenever possible we will use a newline instead of a
|
||
semicolon, leading to more readable output of uglified code (size before
|
||
gzip could be smaller; size after gzip insignificantly larger).
|
||
- `preamble` (default `null`) -- when passed it must be a string and
|
||
it will be prepended to the output literally. The source map will
|
||
adjust for this text. Can be used to insert a comment containing
|
||
licensing information, for example.
|
||
- `quote_style` (default `0`) -- preferred quote style for strings (affects
|
||
quoted property names and directives as well):
|
||
- `0` -- prefers double quotes, switches to single quotes when there are
|
||
more double quotes in the string itself.
|
||
- `1` -- always use single quotes
|
||
- `2` -- always use double quotes
|
||
- `3` -- always use the original quotes
|
||
- `keep_quoted_props` (default `false`) -- when turned on, prevents stripping
|
||
quotes from property names in object literals.
|
||
|
||
### Keeping copyright notices or other comments
|
||
|
||
You can pass `--comments` to retain certain comments in the output. By
|
||
default it will keep JSDoc-style comments that contain "@preserve",
|
||
"@license" or "@cc_on" (conditional compilation for IE). You can pass
|
||
`--comments all` to keep all the comments, or a valid JavaScript regexp to
|
||
keep only comments that match this regexp. For example `--comments
|
||
'/foo|bar/'` will keep only comments that contain "foo" or "bar".
|
||
|
||
Note, however, that there might be situations where comments are lost. For
|
||
example:
|
||
```javascript
|
||
function f() {
|
||
/** @preserve Foo Bar */
|
||
function g() {
|
||
// this function is never called
|
||
}
|
||
return something();
|
||
}
|
||
```
|
||
|
||
Even though it has "@preserve", the comment will be lost because the inner
|
||
function `g` (which is the AST node to which the comment is attached to) is
|
||
discarded by the compressor as not referenced.
|
||
|
||
The safest comments where to place copyright information (or other info that
|
||
needs to be kept in the output) are comments attached to toplevel nodes.
|
||
|
||
## Support for the SpiderMonkey AST
|
||
|
||
UglifyJS2 has its own abstract syntax tree format; for
|
||
[practical reasons](http://lisperator.net/blog/uglifyjs-why-not-switching-to-spidermonkey-ast/)
|
||
we can't easily change to using the SpiderMonkey AST internally. However,
|
||
UglifyJS now has a converter which can import a SpiderMonkey AST.
|
||
|
||
For example [Acorn][acorn] is a super-fast parser that produces a
|
||
SpiderMonkey AST. It has a small CLI utility that parses one file and dumps
|
||
the AST in JSON on the standard output. To use UglifyJS to mangle and
|
||
compress that:
|
||
|
||
acorn file.js | uglifyjs --spidermonkey -m -c
|
||
|
||
The `--spidermonkey` option tells UglifyJS that all input files are not
|
||
JavaScript, but JS code described in SpiderMonkey AST in JSON. Therefore we
|
||
don't use our own parser in this case, but just transform that AST into our
|
||
internal AST.
|
||
|
||
### Use Acorn for parsing
|
||
|
||
More for fun, I added the `--acorn` option which will use Acorn to do all
|
||
the parsing. If you pass this option, UglifyJS will `require("acorn")`.
|
||
|
||
Acorn is really fast (e.g. 250ms instead of 380ms on some 650K code), but
|
||
converting the SpiderMonkey tree that Acorn produces takes another 150ms so
|
||
in total it's a bit more than just using UglifyJS's own parser.
|
||
|
||
### Using UglifyJS to transform SpiderMonkey AST
|
||
|
||
Now you can use UglifyJS as any other intermediate tool for transforming
|
||
JavaScript ASTs in SpiderMonkey format.
|
||
|
||
Example:
|
||
|
||
```javascript
|
||
function uglify(ast, options, mangle) {
|
||
// Conversion from SpiderMonkey AST to internal format
|
||
var uAST = UglifyJS.AST_Node.from_mozilla_ast(ast);
|
||
|
||
// Compression
|
||
uAST.figure_out_scope();
|
||
uAST = UglifyJS.Compressor(options).compress(uAST);
|
||
|
||
// Mangling (optional)
|
||
if (mangle) {
|
||
uAST.figure_out_scope();
|
||
uAST.compute_char_frequency();
|
||
uAST.mangle_names();
|
||
}
|
||
|
||
// Back-conversion to SpiderMonkey AST
|
||
return uAST.to_mozilla_ast();
|
||
}
|
||
```
|
||
|
||
Check out
|
||
[original blog post](http://rreverser.com/using-mozilla-ast-with-uglifyjs/)
|
||
for details.
|
||
|
||
API Reference
|
||
-------------
|
||
|
||
Assuming installation via NPM, you can load UglifyJS in your application
|
||
like this:
|
||
```javascript
|
||
var UglifyJS = require("uglify-js");
|
||
```
|
||
|
||
It exports a lot of names, but I'll discuss here the basics that are needed
|
||
for parsing, mangling and compressing a piece of code. The sequence is (1)
|
||
parse, (2) compress, (3) mangle, (4) generate output code.
|
||
|
||
### The simple way
|
||
|
||
There's a single toplevel function which combines all the steps. If you
|
||
don't need additional customization, you might want to go with `minify`.
|
||
Example:
|
||
```javascript
|
||
var result = UglifyJS.minify("/path/to/file.js");
|
||
console.log(result.code); // minified output
|
||
// if you need to pass code instead of file name
|
||
var result = UglifyJS.minify("var b = function () {};", {fromString: true});
|
||
```
|
||
|
||
You can also compress multiple files:
|
||
```javascript
|
||
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ]);
|
||
console.log(result.code);
|
||
```
|
||
|
||
To generate a source map:
|
||
```javascript
|
||
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], {
|
||
outSourceMap: "out.js.map"
|
||
});
|
||
console.log(result.code); // minified output
|
||
console.log(result.map);
|
||
```
|
||
|
||
To generate a source map with the fromString option, you can also use an object:
|
||
```javascript
|
||
var result = UglifyJS.minify({"file1.js": "var a = function () {};"}, {
|
||
outSourceMap: "out.js.map",
|
||
outFileName: "out.js",
|
||
fromString: true
|
||
});
|
||
```
|
||
|
||
Note that the source map is not saved in a file, it's just returned in
|
||
`result.map`. The value passed for `outSourceMap` is only used to set
|
||
`//# sourceMappingURL=out.js.map` in `result.code`. The value of
|
||
`outFileName` is only used to set `file` attribute in source map file.
|
||
|
||
The `file` attribute in the source map (see [the spec][sm-spec]) will
|
||
use `outFileName` firstly, if it's falsy, then will be deduced from
|
||
`outSourceMap` (by removing `'.map'`).
|
||
|
||
You can set option `sourceMapInline` to be `true` and source map will
|
||
be appended to code.
|
||
|
||
You can also specify sourceRoot property to be included in source map:
|
||
```javascript
|
||
var result = UglifyJS.minify([ "file1.js", "file2.js", "file3.js" ], {
|
||
outSourceMap: "out.js.map",
|
||
sourceRoot: "http://example.com/src"
|
||
});
|
||
```
|
||
|
||
If you're compressing compiled JavaScript and have a source map for it, you
|
||
can use the `inSourceMap` argument:
|
||
```javascript
|
||
var result = UglifyJS.minify("compiled.js", {
|
||
inSourceMap: "compiled.js.map",
|
||
outSourceMap: "minified.js.map"
|
||
});
|
||
// same as before, it returns `code` and `map`
|
||
```
|
||
|
||
If your input source map is not in a file, you can pass it in as an object
|
||
using the `inSourceMap` argument:
|
||
|
||
```javascript
|
||
var result = UglifyJS.minify("compiled.js", {
|
||
inSourceMap: JSON.parse(my_source_map_string),
|
||
outSourceMap: "minified.js.map"
|
||
});
|
||
```
|
||
|
||
The `inSourceMap` is only used if you also request `outSourceMap` (it makes
|
||
no sense otherwise).
|
||
|
||
To set the source map url, use the `sourceMapUrl` option.
|
||
If you're using the X-SourceMap header instead, you can just set the `sourceMapUrl` option to false.
|
||
Defaults to outSourceMap:
|
||
|
||
```javascript
|
||
var result = UglifyJS.minify([ "file1.js" ], {
|
||
outSourceMap: "out.js.map",
|
||
sourceMapUrl: "localhost/out.js.map"
|
||
});
|
||
```
|
||
|
||
Other options:
|
||
|
||
- `warnings` (default `false`) — pass `true` to display compressor warnings.
|
||
|
||
- `fromString` (default `false`) — if you pass `true` then you can pass
|
||
JavaScript source code, rather than file names.
|
||
|
||
- `mangle` (default `true`) — pass `false` to skip mangling names, or pass
|
||
an object to specify mangling options (see below).
|
||
|
||
- `mangleProperties` (default `false`) — pass an object to specify custom
|
||
mangle property options.
|
||
|
||
- `output` (default `null`) — pass an object if you wish to specify
|
||
additional [output options][codegen]. The defaults are optimized
|
||
for best compression.
|
||
|
||
- `compress` (default `{}`) — pass `false` to skip compressing entirely.
|
||
Pass an object to specify custom [compressor options][compressor].
|
||
|
||
- `parse` (default {}) — pass an object if you wish to specify some
|
||
additional [parser options][parser]. (not all options available... see below)
|
||
|
||
##### mangle
|
||
|
||
- `except` - pass an array of identifiers that should be excluded from mangling
|
||
|
||
- `toplevel` — mangle names declared in the toplevel scope (disabled by
|
||
default).
|
||
|
||
- `eval` — mangle names visible in scopes where eval or with are used
|
||
(disabled by default).
|
||
|
||
- `keep_fnames` -- default `false`. Pass `true` to not mangle
|
||
function names. Useful for code relying on `Function.prototype.name`.
|
||
See also: the `keep_fnames` [compress option](#compressor-options).
|
||
|
||
Examples:
|
||
|
||
```javascript
|
||
//tst.js
|
||
var globalVar;
|
||
function funcName(firstLongName, anotherLongName)
|
||
{
|
||
var myVariable = firstLongName + anotherLongName;
|
||
}
|
||
|
||
UglifyJS.minify("tst.js").code;
|
||
// 'function funcName(a,n){}var globalVar;'
|
||
|
||
UglifyJS.minify("tst.js", { mangle: { except: ['firstLongName'] } }).code;
|
||
// 'function funcName(firstLongName,a){}var globalVar;'
|
||
|
||
UglifyJS.minify("tst.js", { mangle: { toplevel: true } }).code;
|
||
// 'function n(n,a){}var a;'
|
||
```
|
||
|
||
##### mangleProperties options
|
||
|
||
- `regex` — Pass a RegExp to only mangle certain names (maps to the `--mangle-regex` CLI arguments option)
|
||
- `ignore_quoted` – Only mangle unquoted property names (maps to the `--mangle-props 2` CLI arguments option)
|
||
- `debug` – Mangle names with the original name still present (maps to the `--mangle-props-debug` CLI arguments option). Defaults to `false`. Pass an empty string to enable, or a non-empty string to set the suffix.
|
||
|
||
We could add more options to `UglifyJS.minify` — if you need additional
|
||
functionality please suggest!
|
||
|
||
### The hard way
|
||
|
||
Following there's more detailed API info, in case the `minify` function is
|
||
too simple for your needs.
|
||
|
||
#### The parser
|
||
```javascript
|
||
var toplevel_ast = UglifyJS.parse(code, options);
|
||
```
|
||
|
||
`options` is optional and if present it must be an object. The following
|
||
properties are available:
|
||
|
||
- `strict` — disable automatic semicolon insertion and support for trailing
|
||
comma in arrays and objects
|
||
- `bare_returns` — Allow return outside of functions. (maps to the
|
||
`--bare-returns` CLI arguments option and available to `minify` `parse`
|
||
other options object)
|
||
- `filename` — the name of the file where this code is coming from
|
||
- `toplevel` — a `toplevel` node (as returned by a previous invocation of
|
||
`parse`)
|
||
|
||
The last two options are useful when you'd like to minify multiple files and
|
||
get a single file as the output and a proper source map. Our CLI tool does
|
||
something like this:
|
||
```javascript
|
||
var toplevel = null;
|
||
files.forEach(function(file){
|
||
var code = fs.readFileSync(file, "utf8");
|
||
toplevel = UglifyJS.parse(code, {
|
||
filename: file,
|
||
toplevel: toplevel
|
||
});
|
||
});
|
||
```
|
||
|
||
After this, we have in `toplevel` a big AST containing all our files, with
|
||
each token having proper information about where it came from.
|
||
|
||
#### Scope information
|
||
|
||
UglifyJS contains a scope analyzer that you need to call manually before
|
||
compressing or mangling. Basically it augments various nodes in the AST
|
||
with information about where is a name defined, how many times is a name
|
||
referenced, if it is a global or not, if a function is using `eval` or the
|
||
`with` statement etc. I will discuss this some place else, for now what's
|
||
important to know is that you need to call the following before doing
|
||
anything with the tree:
|
||
```javascript
|
||
toplevel.figure_out_scope()
|
||
```
|
||
|
||
#### Compression
|
||
|
||
Like this:
|
||
```javascript
|
||
var compressor = UglifyJS.Compressor(options);
|
||
var compressed_ast = compressor.compress(toplevel);
|
||
```
|
||
|
||
The `options` can be missing. Available options are discussed above in
|
||
“Compressor options”. Defaults should lead to best compression in most
|
||
scripts.
|
||
|
||
The compressor is destructive, so don't rely that `toplevel` remains the
|
||
original tree.
|
||
|
||
#### Mangling
|
||
|
||
After compression it is a good idea to call again `figure_out_scope` (since
|
||
the compressor might drop unused variables / unreachable code and this might
|
||
change the number of identifiers or their position). Optionally, you can
|
||
call a trick that helps after Gzip (counting character frequency in
|
||
non-mangleable words). Example:
|
||
```javascript
|
||
compressed_ast.figure_out_scope();
|
||
compressed_ast.compute_char_frequency();
|
||
compressed_ast.mangle_names();
|
||
```
|
||
|
||
#### Generating output
|
||
|
||
AST nodes have a `print` method that takes an output stream. Essentially,
|
||
to generate code you do this:
|
||
```javascript
|
||
var stream = UglifyJS.OutputStream(options);
|
||
compressed_ast.print(stream);
|
||
var code = stream.toString(); // this is your minified code
|
||
```
|
||
|
||
or, for a shortcut you can do:
|
||
```javascript
|
||
var code = compressed_ast.print_to_string(options);
|
||
```
|
||
|
||
As usual, `options` is optional. The output stream accepts a lot of options,
|
||
most of them documented above in section “Beautifier options”. The two
|
||
which we care about here are `source_map` and `comments`.
|
||
|
||
#### Keeping comments in the output
|
||
|
||
In order to keep certain comments in the output you need to pass the
|
||
`comments` option. Pass a RegExp (as string starting and closing with `/`
|
||
or pass a RegExp object), a boolean or a function. Stringified options
|
||
`all` and `some` can be passed too, where `some` behaves like it's cli
|
||
equivalent `--comments` without passing a value. If you pass a RegExp,
|
||
only those comments whose body matches the RegExp will be kept. Note that body
|
||
means without the initial `//` or `/*`. If you pass a function, it will be
|
||
called for every comment in the tree and will receive two arguments: the
|
||
node that the comment is attached to, and the comment token itself.
|
||
|
||
The comment token has these properties:
|
||
|
||
- `type`: "comment1" for single-line comments or "comment2" for multi-line
|
||
comments
|
||
- `value`: the comment body
|
||
- `pos` and `endpos`: the start/end positions (zero-based indexes) in the
|
||
original code where this comment appears
|
||
- `line` and `col`: the line and column where this comment appears in the
|
||
original code
|
||
- `file` — the file name of the original file
|
||
- `nlb` — true if there was a newline before this comment in the original
|
||
code, or if this comment contains a newline.
|
||
|
||
Your function should return `true` to keep the comment, or a falsy value
|
||
otherwise.
|
||
|
||
#### Generating a source mapping
|
||
|
||
You need to pass the `source_map` argument when calling `print`. It needs
|
||
to be a `SourceMap` object (which is a thin wrapper on top of the
|
||
[source-map][source-map] library).
|
||
|
||
Example:
|
||
```javascript
|
||
var source_map = UglifyJS.SourceMap(source_map_options);
|
||
var stream = UglifyJS.OutputStream({
|
||
...
|
||
source_map: source_map
|
||
});
|
||
compressed_ast.print(stream);
|
||
|
||
var code = stream.toString();
|
||
var map = source_map.toString(); // json output for your source map
|
||
```
|
||
|
||
The `source_map_options` (optional) can contain the following properties:
|
||
|
||
- `file`: the name of the JavaScript output file that this mapping refers to
|
||
- `root`: the `sourceRoot` property (see the [spec][sm-spec])
|
||
- `orig`: the "original source map", handy when you compress generated JS
|
||
and want to map the minified output back to the original code where it
|
||
came from. It can be simply a string in JSON, or a JSON object containing
|
||
the original source map.
|
||
|
||
[acorn]: https://github.com/ternjs/acorn
|
||
[source-map]: https://github.com/mozilla/source-map
|
||
[sm-spec]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit
|
||
[codegen]: http://lisperator.net/uglifyjs/codegen
|
||
[compressor]: http://lisperator.net/uglifyjs/compress
|
||
[parser]: http://lisperator.net/uglifyjs/parser
|
||
|
||
#### Support for `const`
|
||
|
||
`const` in `uglify-js@2.x` has function scope and as such behaves much like
|
||
`var` - unlike `const` in ES2015 (ES6) which has block scope. It is recommended
|
||
to avoid using `const` for this reason as it will have undefined behavior when
|
||
run on an ES2015 compatible browser.
|