Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/meteor/uglifyjs2

JavaScript parser / mangler / compressor / beautifier toolkit
https://github.com/meteor/uglifyjs2

Last synced: 9 months ago
JSON representation

JavaScript parser / mangler / compressor / beautifier toolkit

Awesome Lists containing this project

README 

          
UglifyJS 2

==========



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).



Install

-------



From NPM:



    npm install uglify-js



From Git:



    git clone git://github.com/mishoo/UglifyJS2.git

    cd UglifyJS2

    npm link .



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.



The available options are:



    --source-map       Specify an output file where to generate source map.

                                                                          [string]

    --source-map-root  The path to the original source to be included in the

                       source map.                                        [string]

    --in-source-map    Input source map, useful if you're compressing JS that was

                       generated from some other original code.

    -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.

    -o, --output       Output file (default STDOUT).

    -b, --beautify     Beautify output/specify output options.            [string]

    -m, --mangle       Mangle names/pass mangler options.                 [string]

    -r, --reserved     Reserved names to exclude from mangling.

    -c, --compress     Enable compressor/pass compressor options. Pass options

                       like -c hoist_vars=false,if_return=false. Use -c with no

                       argument to use the default compression options.   [string]

    -d, --define       Global definitions                                 [string]

    --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 (needs to start with a slash) to keep

                       only comments that match.

                       Note that currently not *all* comments can be kept when

                       compression is on, because of dead code removal or

                       cascading statements into sequences.               [string]

    --stats            Display operations run time on STDERR.            [boolean]

    --acorn            Use Acorn for parsing.                            [boolean]

    --spidermonkey     Assume input fles are SpiderMonkey AST format (as JSON).

                                                                         [boolean]

    --self             Build itself (UglifyJS2) as a library (implies

                       --wrap=UglifyJS --export-all)                     [boolean]

    --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.

                                                                          [string]

    --export-all       Only used when --wrap, this tells UglifyJS to add code to

                       automatically export all globals.                 [boolean]

    -v, --verbose      Verbose                                           [boolean]

    -V, --version      Print version number and exits.                   [boolean]



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`.  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`).  Optionally you

can pass `-m sort=true` (we'll possibly have other flags in the future) in order

to assign shorter names to most frequently used variables.  This saves a few

hundred bytes on jQuery before gzip, but the output is _bigger_ after gzip

(and seems to happen for other libraries I tried it on) therefore it's not

enabled 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.



## 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`).



The defaults should be tuned for maximum compression on most code.  Here are

the available options (all are `true` by default, except `hoist_vars`):



- `sequences` -- join consecutive simple statements using the comma operator

- `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` -- apply "unsafe" transformations (discussion below)

- `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`), 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

- `hoist_funs` -- hoist function declarations

- `hoist_vars` -- 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()`

- `warnings` -- display warnings when dropping unreachable code or unused

  declarations etc.



### 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:



    if (DEBUG) {

        console.log("debug stuff");

    }



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:



    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 possible downside of this approach is that the build

will contain the `const` declarations.





## 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

- `inline-script` (default `false`) -- escape the slash in occurrences of

  `