1 #+TITLE: UglifyJS -- a JavaScript parser/compressor/beautifier
2 #+KEYWORDS: javascript, js, parser, compiler, compressor, mangle, minify, minifier
3 #+DESCRIPTION: a JavaScript parser/compressor/beautifier in JavaScript
4 #+STYLE: <link rel="stylesheet" type="text/css" href="docstyle.css" />
6 #+EMAIL: mihai.bazon@gmail.com
8 * UglifyJS --- a JavaScript parser/compressor/beautifier
10 This package implements a general-purpose JavaScript
11 parser/compressor/beautifier toolkit. It is developed on [[http://nodejs.org/][NodeJS]], but it
12 should work on any JavaScript platform supporting the CommonJS module system
13 (and if your platform of choice doesn't support CommonJS, you can easily
14 implement it, or discard the =exports.*= lines from UglifyJS sources).
16 The tokenizer/parser generates an abstract syntax tree from JS code. You
17 can then traverse the AST to learn more about the code, or do various
18 manipulations on it. This part is implemented in [[../lib/parse-js.js][parse-js.js]] and it's a
19 port to JavaScript of the excellent [[http://marijn.haverbeke.nl/parse-js/][parse-js]] Common Lisp library from [[http://marijn.haverbeke.nl/][Marijn
22 ( See [[http://github.com/mishoo/cl-uglify-js][cl-uglify-js]] if you're looking for the Common Lisp version of
25 The second part of this package, implemented in [[../lib/process.js][process.js]], inspects and
26 manipulates the AST generated by the parser to provide the following:
28 - ability to re-generate JavaScript code from the AST. Optionally
29 indented---you can use this if you want to “beautify” a program that has
30 been compressed, so that you can inspect the source. But you can also run
31 our code generator to print out an AST without any whitespace, so you
32 achieve compression as well.
34 - shorten variable names (usually to single characters). Our mangler will
35 analyze the code and generate proper variable names, depending on scope
36 and usage, and is smart enough to deal with globals defined elsewhere, or
37 with =eval()= calls or =with{}= statements. In short, if =eval()= or
38 =with{}= are used in some scope, then all variables in that scope and any
39 variables in the parent scopes will remain unmangled, and any references
40 to such variables remain unmangled as well.
42 - various small optimizations that may lead to faster code but certainly
43 lead to smaller code. Where possible, we do the following:
45 - foo["bar"] ==> foo.bar
47 - remove block brackets ={}=
49 - join consecutive var declarations:
50 var a = 10; var b = 20; ==> var a=10,b=20;
52 - resolve simple constant expressions: 1 +2 * 3 ==> 7. We only do the
53 replacement if the result occupies less bytes; for example 1/3 would
54 translate to 0.333333333333, so in this case we don't replace it.
56 - consecutive statements in blocks are merged into a sequence; in many
57 cases, this leaves blocks with a single statement, so then we can remove
60 - various optimizations for IF statements:
62 - if (foo) bar(); else baz(); ==> foo?bar():baz();
63 - if (!foo) bar(); else baz(); ==> foo?baz():bar();
64 - if (foo) bar(); ==> foo&&bar();
65 - if (!foo) bar(); ==> foo||bar();
66 - if (foo) return bar(); else return baz(); ==> return foo?bar():baz();
67 - if (foo) return bar(); else something(); ==> {if(foo)return bar();something()}
69 - remove some unreachable code and warn about it (code that follows a
70 =return=, =throw=, =break= or =continue= statement, except
71 function/variable declarations).
73 - act a limited version of a pre-processor (c.f. the pre-processor of
74 C/C++) to allow you to safely replace selected global symbols with
75 specified values. When combined with the optimisations above this can
76 make UglifyJS operate slightly more like a compilation process, in
77 that when certain symbols are replaced by constant values, entire code
78 blocks may be optimised away as unreachable.
80 ** <<Unsafe transformations>>
82 The following transformations can in theory break code, although they're
83 probably safe in most practical cases. To enable them you need to pass the
86 *** Calls involving the global Array constructor
88 The following transformations occur:
91 new Array(1, 2, 3, 4) => [1,2,3,4]
92 Array(a, b, c) => [a,b,c]
93 new Array(5) => Array(5)
94 new Array(a) => Array(a)
97 These are all safe if the Array name isn't redefined. JavaScript does allow
98 one to globally redefine Array (and pretty much everything, in fact) but I
99 personally don't see why would anyone do that.
101 UglifyJS does handle the case where Array is redefined locally, or even
102 globally but with a =function= or =var= declaration. Therefore, in the
103 following cases UglifyJS *doesn't touch* calls or instantiations of Array:
106 // case 1. globally declared variable
111 // or (can be declared later)
115 // or (can be a function)
117 function Array() { ... }
119 // case 2. declared in a function
121 a = new Array(1, 2, 3);
128 return Array(5, 6, 7);
133 return new Array(1, 2, 3, 4);
134 function Array() { ... }
140 *** =obj.toString()= ==> =obj+“”=
144 UglifyJS is now available through NPM --- =npm install uglify-js= should do
147 ** Install latest code from GitHub
150 ## clone the repository
151 mkdir -p /where/you/wanna/put/it
152 cd /where/you/wanna/put/it
153 git clone git://github.com/mishoo/UglifyJS.git
155 ## make the module available to Node
156 mkdir -p ~/.node_libraries/
157 cd ~/.node_libraries/
158 ln -s /where/you/wanna/put/it/UglifyJS/uglify-js.js
160 ## and if you want the CLI script too:
163 ln -s /where/you/wanna/put/it/UglifyJS/bin/uglifyjs
164 # (then add ~/bin to your $PATH if it's not there already)
169 There is a command-line tool that exposes the functionality of this library
170 for your shell-scripting needs:
173 uglifyjs [ options... ] [ filename ]
176 =filename= should be the last argument and should name the file from which
177 to read the JavaScript code. If you don't specify it, it will read code
182 - =-b= or =--beautify= --- output indented code; when passed, additional
183 options control the beautifier:
185 - =-i N= or =--indent N= --- indentation level (number of spaces)
187 - =-q= or =--quote-keys= --- quote keys in literal objects (by default,
188 only keys that cannot be identifier names will be quotes).
190 - =--ascii= --- pass this argument to encode non-ASCII characters as
191 =\uXXXX= sequences. By default UglifyJS won't bother to do it and will
192 output Unicode characters instead. (the output is always encoded in UTF8,
193 but if you pass this option you'll only get ASCII).
195 - =-nm= or =--no-mangle= --- don't mangle names.
197 - =-nmf= or =--no-mangle-functions= -- in case you want to mangle variable
198 names, but not touch function names.
200 - =-ns= or =--no-squeeze= --- don't call =ast_squeeze()= (which does various
201 optimizations that result in smaller, less readable code).
203 - =-mt= or =--mangle-toplevel= --- mangle names in the toplevel scope too
204 (by default we don't do this).
206 - =--no-seqs= --- when =ast_squeeze()= is called (thus, unless you pass
207 =--no-squeeze=) it will reduce consecutive statements in blocks into a
208 sequence. For example, "a = 10; b = 20; foo();" will be written as
209 "a=10,b=20,foo();". In various occasions, this allows us to discard the
210 block brackets (since the block becomes a single statement). This is ON
211 by default because it seems safe and saves a few hundred bytes on some
212 libs that I tested it on, but pass =--no-seqs= to disable it.
214 - =--no-dead-code= --- by default, UglifyJS will remove code that is
215 obviously unreachable (code that follows a =return=, =throw=, =break= or
216 =continue= statement and is not a function/variable declaration). Pass
217 this option to disable this optimization.
219 - =-nc= or =--no-copyright= --- by default, =uglifyjs= will keep the initial
220 comment tokens in the generated code (assumed to be copyright information
221 etc.). If you pass this it will discard it.
223 - =-o filename= or =--output filename= --- put the result in =filename=. If
224 this isn't given, the result goes to standard output (or see next one).
226 - =--overwrite= --- if the code is read from a file (not from STDIN) and you
227 pass =--overwrite= then the output will be written in the same file.
229 - =--ast= --- pass this if you want to get the Abstract Syntax Tree instead
230 of JavaScript as output. Useful for debugging or learning more about the
233 - =-v= or =--verbose= --- output some notes on STDERR (for now just how long
234 each operation takes).
236 - =-d SYMBOL[=VALUE]= or =--define SYMBOL[=VALUE]= --- will replace
237 all instances of the specified symbol where used as an identifier
238 (except where symbol has properly declared by a var declaration or
239 use as function parameter or similar) with the specified value. This
240 argument may be specified multiple times to define multiple
241 symbols - if no value is specified the symbol will be replaced with
242 the value =true=, or you can specify a numeric value (such as
243 =1024=), a quoted string value (such as ="object"= or
244 ='https://github.com'=), or the name of another symbol or keyword
245 (such as =null= or =document=).
246 This allows you, for example, to assign meaningful names to key
247 constant values but discard the symbolic names in the uglified
248 version for brevity/efficiency, or when used wth care, allows
249 UglifyJS to operate as a form of *conditional compilation*
250 whereby defining appropriate values may, by dint of the constant
251 folding and dead code removal features above, remove entire
252 superfluous code blocks (e.g. completely remove instrumentation or
253 trace code for production use).
254 Where string values are being defined, the handling of quotes are
255 likely to be subject to the specifics of your command shell
256 environment, so you may need to experiment with quoting styles
257 depending on your platform, or you may find the option
258 =--define-from-module= more suitable for use.
260 - =-define-from-module SOMEMODULE= --- will load the named module (as
261 per the NodeJS =require()= function) and iterate all the exported
262 properties of the module defining them as symbol names to be defined
263 (as if by the =--define= option) per the name of each property
264 (i.e. without the module name prefix) and given the value of the
265 property. This is a much easier way to handle and document groups of
266 symbols to be defined rather than a large number of =--define=
269 - =--unsafe= --- enable other additional optimizations that are known to be
270 unsafe in some contrived situations, but could still be generally useful.
273 - foo.toString() ==> foo+""
274 - new Array(x,...) ==> [x,...]
275 - new Array(x) ==> Array(x)
277 - =--max-line-len= (default 32K characters) --- add a newline after around
278 32K characters. I've seen both FF and Chrome croak when all the code was
279 on a single line of around 670K. Pass --max-line-len 0 to disable this
282 - =--reserved-names= --- some libraries rely on certain names to be used, as
283 pointed out in issue #92 and #81, so this option allow you to exclude such
284 names from the mangler. For example, to keep names =require= and =$super=
285 intact you'd specify --reserved-names "require,$super".
287 - =--inline-script= -- when you want to include the output literally in an
288 HTML =<script>= tag you can use this option to prevent =</script= from
289 showing up in the output.
291 - =--lift-vars= -- when you pass this, UglifyJS will apply the following
292 transformations (see the notes in API, =ast_lift_variables=):
294 - put all =var= declarations at the start of the scope
295 - make sure a variable is declared only once
296 - discard unused function arguments
297 - discard unused inner (named) functions
298 - finally, try to merge assignments into that one =var= declaration, if
303 To use the library from JavaScript, you'd do the following (example for
307 var jsp = require("uglify-js").parser;
308 var pro = require("uglify-js").uglify;
310 var orig_code = "... JS code here";
311 var ast = jsp.parse(orig_code); // parse code and get the initial AST
312 ast = pro.ast_mangle(ast); // get a new AST with mangled names
313 ast = pro.ast_squeeze(ast); // get an AST with compression optimizations
314 var final_code = pro.gen_code(ast); // compressed code here
317 The above performs the full compression that is possible right now. As you
318 can see, there are a sequence of steps which you can apply. For example if
319 you want compressed output but for some reason you don't want to mangle
320 variable names, you would simply skip the line that calls
321 =pro.ast_mangle(ast)=.
323 Some of these functions take optional arguments. Here's a description:
325 - =jsp.parse(code, strict_semicolons)= -- parses JS code and returns an AST.
326 =strict_semicolons= is optional and defaults to =false=. If you pass
327 =true= then the parser will throw an error when it expects a semicolon and
328 it doesn't find it. For most JS code you don't want that, but it's useful
329 if you want to strictly sanitize your code.
331 - =pro.ast_lift_variables(ast)= -- merge and move =var= declarations to the
332 scop of the scope; discard unused function arguments or variables; discard
333 unused (named) inner functions. It also tries to merge assignments
334 following the =var= declaration into it.
336 If your code is very hand-optimized concerning =var= declarations, this
337 lifting variable declarations might actually increase size. For me it
338 helps out. On jQuery it adds 865 bytes (243 after gzip). YMMV. Also
339 note that (since it's not enabled by default) this operation isn't yet
340 heavily tested (please report if you find issues!).
342 Note that although it might increase the image size (on jQuery it gains
343 865 bytes, 243 after gzip) it's technically more correct: in certain
344 situations, dead code removal might drop variable declarations, which
345 would not happen if the variables are lifted in advance.
347 Here's an example of what it does:
350 function f(a, b, c, d, e) {
355 for (var i = 1; i < 10; ++i) {
358 for (var i = 0; i < 1; ++i) {
361 function foo(){ ... }
362 function bar(){ ... }
363 function baz(){ ... }
366 // transforms into ==>
368 function f(a, b, c) {
369 var i, boo, w = 10, q = 20;
370 for (i = 1; i < 10; ++i) {
373 for (i = 0; i < 1; ++i) {
376 function foo() { ... }
377 function bar() { ... }
381 - =pro.ast_mangle(ast, options)= -- generates a new AST containing mangled
382 (compressed) variable and function names. It supports the following
385 - =toplevel= -- mangle toplevel names (by default we don't touch them).
386 - =except= -- an array of names to exclude from compression.
387 - =defines= -- an object with properties named after symbols to
388 replace (see the =--define= option for the script) and the values
389 representing the AST replacement value.
391 - =pro.ast_squeeze(ast, options)= -- employs further optimizations designed
392 to reduce the size of the code that =gen_code= would generate from the
393 AST. Returns a new AST. =options= can be a hash; the supported options
396 - =make_seqs= (default true) which will cause consecutive statements in a
397 block to be merged using the "sequence" (comma) operator
399 - =dead_code= (default true) which will remove unreachable code.
401 - =pro.gen_code(ast, options)= -- generates JS code from the AST. By
402 default it's minified, but using the =options= argument you can get nicely
403 formatted output. =options= is, well, optional :-) and if you pass it it
404 must be an object and supports the following properties (below you can see
407 - =beautify: false= -- pass =true= if you want indented output
408 - =indent_start: 0= (only applies when =beautify= is =true=) -- initial
409 indentation in spaces
410 - =indent_level: 4= (only applies when =beautify= is =true=) --
411 indentation level, in spaces (pass an even number)
412 - =quote_keys: false= -- if you pass =true= it will quote all keys in
414 - =space_colon: false= (only applies when =beautify= is =true=) -- wether
415 to put a space before the colon in object literals
416 - =ascii_only: false= -- pass =true= if you want to encode non-ASCII
417 characters as =\uXXXX=.
418 - =inline_script: false= -- pass =true= to escape occurrences of
419 =</script= in strings
421 *** Beautifier shortcoming -- no more comments
423 The beautifier can be used as a general purpose indentation tool. It's
424 useful when you want to make a minified file readable. One limitation,
425 though, is that it discards all comments, so you don't really want to use it
426 to reformat your code, unless you don't have, or don't care about, comments.
428 In fact it's not the beautifier who discards comments --- they are dumped at
429 the parsing stage, when we build the initial AST. Comments don't really
430 make sense in the AST, and while we could add nodes for them, it would be
431 inconvenient because we'd have to add special rules to ignore them at all
432 the processing stages.
434 *** Use as a code pre-processor
436 The =--define= option can be used, particularly when combined with the
437 constant folding logic, as a form of pre-processor to enable or remove
438 particular constructions, such as might be used for instrumenting
439 development code, or to produce variations aimed at a specific
442 The code below illustrates the way this can be done, and how the
443 symbol replacement is performed.
446 CLAUSE1: if (typeof DEVMODE === 'undefined') {
450 CLAUSE2: function init() {
452 console.log("init() called");
455 DEVMODE && console.log("init() complete");
458 CLAUSE3: function reportDeviceStatus(device) {
459 var DEVMODE = device.mode, DEVNAME = device.name;
460 if (DEVMODE === 'open') {
466 When the above code is normally executed, the undeclared global
467 variable =DEVMODE= will be assigned the value *true* (see =CLAUSE1=)
468 and so the =init()= function (=CLAUSE2=) will write messages to the
469 console log when executed, but in =CLAUSE3= a locally declared
470 variable will mask access to the =DEVMODE= global symbol.
472 If the above code is processed by UglifyJS with an argument of
473 =--define DEVMODE=false= then UglifyJS will replace =DEVMODE= with the
474 boolean constant value *false* within =CLAUSE1= and =CLAUSE2=, but it
475 will leave =CLAUSE3= as it stands because there =DEVMODE= resolves to
476 a validly declared variable.
478 And more so, the constant-folding features of UglifyJS will recognise
479 that the =if= condition of =CLAUSE1= is thus always false, and so will
480 remove the test and body of =CLAUSE1= altogether (including the
481 otherwise slightly problematical statement =false = true;= which it
482 will have formed by replacing =DEVMODE= in the body). Similarly,
483 within =CLAUSE2= both calls to =console.log()= will be removed
486 In this way you can mimic, to a limited degree, the functionality of
487 the C/C++ pre-processor to enable or completely remove blocks
488 depending on how certain symbols are defined - perhaps using UglifyJS
489 to generate different versions of source aimed at different
492 It is recommmended (but not made mandatory) that symbols designed for
493 this purpose are given names consisting of =UPPER_CASE_LETTERS= to
494 distinguish them from other (normal) symbols and avoid the sort of
495 clash that =CLAUSE3= above illustrates.
497 ** Compression -- how good is it?
499 Here are updated statistics. (I also updated my Google Closure and YUI
502 We're still a lot better than YUI in terms of compression, though slightly
503 slower. We're still a lot faster than Closure, and compression after gzip
506 | File | UglifyJS | UglifyJS+gzip | Closure | Closure+gzip | YUI | YUI+gzip |
507 |-----------------------------+------------------+---------------+------------------+--------------+------------------+----------|
508 | jquery-1.6.2.js | 91001 (0:01.59) | 31896 | 90678 (0:07.40) | 31979 | 101527 (0:01.82) | 34646 |
509 | paper.js | 142023 (0:01.65) | 43334 | 134301 (0:07.42) | 42495 | 173383 (0:01.58) | 48785 |
510 | prototype.js | 88544 (0:01.09) | 26680 | 86955 (0:06.97) | 26326 | 92130 (0:00.79) | 28624 |
511 | thelib-full.js (DynarchLIB) | 251939 (0:02.55) | 72535 | 249911 (0:09.05) | 72696 | 258869 (0:01.94) | 76584 |
515 Unfortunately, for the time being there is no automated test suite. But I
516 ran the compressor manually on non-trivial code, and then I tested that the
517 generated code works as expected. A few hundred times.
519 DynarchLIB was started in times when there was no good JS minifier.
520 Therefore I was quite religious about trying to write short code manually,
521 and as such DL contains a lot of syntactic hacks[1] such as “foo == bar ? a
522 = 10 : b = 20”, though the more readable version would clearly be to use
525 Since the parser/compressor runs fine on DL and jQuery, I'm quite confident
526 that it's solid enough for production use. If you can identify any bugs,
527 I'd love to hear about them ([[http://groups.google.com/group/uglifyjs][use the Google Group]] or email me directly).
529 [1] I even reported a few bugs and suggested some fixes in the original
530 [[http://marijn.haverbeke.nl/parse-js/][parse-js]] library, and Marijn pushed fixes literally in minutes.
534 - Twitter: [[http://twitter.com/UglifyJS][@UglifyJS]]
535 - Project at GitHub: [[http://github.com/mishoo/UglifyJS][http://github.com/mishoo/UglifyJS]]
536 - Google Group: [[http://groups.google.com/group/uglifyjs][http://groups.google.com/group/uglifyjs]]
537 - Common Lisp JS parser: [[http://marijn.haverbeke.nl/parse-js/][http://marijn.haverbeke.nl/parse-js/]]
538 - JS-to-Lisp compiler: [[http://github.com/marijnh/js][http://github.com/marijnh/js]]
539 - Common Lisp JS uglifier: [[http://github.com/mishoo/cl-uglify-js][http://github.com/mishoo/cl-uglify-js]]
543 UglifyJS is released under the BSD license:
546 Copyright 2010 (c) Mihai Bazon <mihai.bazon@gmail.com>
547 Based on parse-js (http://marijn.haverbeke.nl/parse-js/).
549 Redistribution and use in source and binary forms, with or without
550 modification, are permitted provided that the following conditions
553 * Redistributions of source code must retain the above
554 copyright notice, this list of conditions and the following
557 * Redistributions in binary form must reproduce the above
558 copyright notice, this list of conditions and the following
559 disclaimer in the documentation and/or other materials
560 provided with the distribution.
562 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER “AS IS” AND ANY
563 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
564 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
565 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
566 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
567 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
568 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
569 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
570 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
571 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
572 THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF