Overview
To request compiled code or other information from the Closure Compiler service,
you must send an HTTP POST request to the URL
https://closure-compiler.appspot.com/compile
. The body of the request must
contain the parameters listed in Required Request
Parameters, and it can also contain any of the optional parameters
listed in Optional Request Parameters.
If the server fails to process your request, you will receive a server error message. These messages are described in the Error Messages section.
Request Parameters
Required Request Parameters
js_code
orcode_url
-
The JavaScript to be compiled. You must include at least one of these parameters, and you can include both.
The
js_code
parameter must be a string containing JavaScript, such asalert('hello')
.The
code_url
parameter must contain the URL of a JavaScript file. You can include multiplecode_url
parameters to specify multiple input files. compilation_level
-
The degree of compression and optimization to apply to your JavaScript. There are three possible compilation levels:
WHITESPACE_ONLY
- Just removes whitespace and comments from your JavaScript.
SIMPLE_OPTIMIZATIONS
- Performs compression and
optimization that does not interfere with the interaction between the
compiled JavaScript and other JavaScript. This level renames only
local variables. See Communicating with the API for more
information about compiling with
SIMPLE_OPTIMIZATIONS
. ADVANCED_OPTIMIZATIONS
- Achieves the highest
level of compression by renaming symbols in your JavaScript. When
using
ADVANCED_OPTIMIZATIONS
compilation you must perform extra steps to preserve references to external symbols. See Advanced Compilation and Externs for more information aboutADVANCED_OPTIMIZATIONS
.
The
compilation_level
parameter defaults to a value ofSIMPLE_OPTIMIZATIONS
. output_format
- The format for the Closure Compiler service's
output. There are three possible output formats:
xml
-
The
xml
output format wraps the requested information in valid XML.The XML output looks like this:
<compilationResult> <compiledCode>var a="hello";alert(a);</compiledCode> <statistics> <originalSize>98</originalSize> <compressedSize>35</compressedSize> <compileTime>0</compileTime> </statistics> </compilationResult>
The
compiledCode
section contains the compressed JavaScript that the Closure Compiler service produced. This section only appears if you include anoutput_info
parameter with a value ofcompiled_code
in the request. Similarly, thestatistics
section only appears if you include anoutput_info
parameter with a value ofstatistics
.If you include an
output_info
parameter with a value ofwarnings
and the compiler produces a warning, the output will include awarnings
tag:<compilationResult> ... <warnings> <warning type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3" line="delete 1;">warning 1</warning> <warning type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="delete 1;">warning 2 </warning> </warnings> ... </compilationResult>
If you include an
output_info
with a value oferrors
, the Closure Compiler service will include anerrors
tag if your code contains a syntax error or other problem that prevents compilation. Theerrors
tag looks like this:<compilationResult> ... <errors> <error type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3" line="var x=-'hello';">error 1 </error> <error type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="var x=-'hello'">error 2 </error> </errors> ... </compilationResult>
The
file
,line
, andcol
attributes of theerror
andwarning
tags indicate where the Closure Compiler service encountered the error.If the Closure Compiler service encounters an error that prevents the processing of your input, the output looks like this:
<compilationResult> <serverErrors> <error code="1">Over quota</error> </serverErrors> </compilationResult>
json
-
The
json
output format wraps the requested information in a JavaScript Object Notation (JSON) string. Evaluation of this string as JavaScript returns a JavaScript Object.The JSON output looks like this:
{ "compiledCode":/* raw code here */, {"errors": [ {"charno":4321, "error":"ERROR: You failed.", "lineno":1234, "file":"default.js", "type":"ERROR_TYPE", "line":"var x=-'hello';"}], "warnings": [ {"charno":4321, "lineno":1234, "file":"default.js", "type":"ERROR_TYPE", "warning":"Warning: You did something wrong!", "line":"delete 1;"}] "serverErrors":[ {"code":123,"error":"Over quota"} ], "statistics":{ "originalSize":10, "compressedSize":3000 "compileTime":10 } }
The JSON format is similar to the XML format: every tag in the XML output corresponds to a property of the same name in the JSON object
text
-
The
text
output format returns raw text without tags or JSON brackets. If theoutput_info
includescompiled_code
, the text contains JavaScript. If theoutput_info
includeswarnings
, the text contains warning messages. If theoutput_info
includesstatistics
, the text contains statistics.
The
output_format
parameter defaults to a value oftext
. output_info
-
Indicates the kind of output you want from the compiler. There are four possible kinds of output:
compiled_code
- A compressed and optimized version of your input JavaScript.
warnings
- Messages that indicate possible bugs in your JavaScript.
errors
- Messages that indicate syntax errors or other errors in your JavaScript.
statistics
-
Information about the degree of compression that the Closure Compiler achieves. For xml output, the Closure Compiler service returns statistics in the following format:
<compilationResult> ... <statistics> <firstStatisticName>24</firstStatisticName> <secondStatisticName>15</secondStatisticName> </statistics> </compilationResult>
Optional Request Parameters
js_externs
-
The value of this parameter must be JavaScript code that declares function names or other symbols. Use
js_externs
to preserve symbols that are defined outside of the code you are compiling. Thejs_externs
parameter only has an effect if you are using acompilation_level
ofADVANCED_OPTIMIZATIONS
. See Advanced Compilation for more information. externs_url
-
The value of this parameter must be the URL of a file containing JavaScript that declares function names or other symbols. The symbols declared in this file are preserved in exactly the same way as symbols listed directly in the
js_externs
parameter. Theexterns_url
parameter only has an effect if you are using acompilation_level
ofADVANCED_OPTIMIZATIONS
. See Advanced Compilation for more information.You can specify this parameter multiple times if you have multiple externs files.
exclude_default_externs
-
By default, the Closure Compiler service uses a standard externs file that declares common externally defined symbols like
document
and all its methods. If you do NOT want to use these common externs, include in your request anexclude_default_externs
parameter with a value oftrue
.See Advanced Compilation and Externs for more information about externs.
output_file_name
-
If present, the Closure Compiler service caches the compiled code for one hour and makes it available through a special URL. During this hour you can test the compiled code by pointing your browser to this URL. The URL has this form:
https://closure-compiler.appspot.com/code/bf067f356d510e1c7b81347eb84f65d2/[value of output_file_name]
formatting
-
If present, this parameter must have a value of
pretty_print
orprint_input_delimiter
. You can provide multipleformatting
parameters in the same request. Thepretty_print
andprint_input_delimiter
values affect different aspects of the formatting, so you can include both without affecting the way either works.pretty_print
-
If the request contains a
formatting
parameter with a value ofpretty_print
, the Closure Compiler service adds line breaks and indentation to its output code to make the code easier for humans to read. For example, output withpretty_print
turned on looks like this:function hello(a) { alert("Hello, " + a) } hello("New user");
Output with
pretty_print
turned off looks like this:function hello(a){alert("Hello, "+a)}hello("New user");
print_input_delimiter
-
If the request contains a
formatting
parameter with a value ofprint_input_delimiter
, the Closure Compiler service adds a separator between the compiler outputs for each file you compile. For example, if you compile two files together, the output looks like this:// Input 0 alert("hi"); // Input 1 alert("bye");
The compiler inserts the
// Input X
delimiters to mark the boundaries between files. Note that the delimiters are comments, so they do not interfere with the execution of the JavaScript.Each JavaScript file you provide with a
code_url
parameter has a corresponding delimited section in the compiler output. The Closure Compiler service treats all input fromjs_code
parameters as if it comes from a single file.Input delimiters have many potential uses, including helping you to figure out which inputs are contributing the most to the size of the compiled code.
-
use_closure_library
-
If you give the
use_closure_library
parameter a value oftrue
, the compiler looks forgoog.require()
statements in the source code and supplies the Closure Library code requested by any such statements. It also performs optimizations designed specifically for Closure Library code. See the Closure Library documentation for more information about the Closure Library. See Finding Your Way around the Closure Library for more information about thegoog.require()
function.The
use_closure_library
parameter defaults tofalse
. warning_level
-
Indicates the amount of information you want from the compiler about possible problems in your code. The
warning_level
parameter only has an effect when anoutput_info
parameter with a value ofwarnings
is also supplied. There are three possible warning levels:QUIET
- Outputs only syntax error messages and warnings
generated by the optimization passes included in
the
compilation_level
for the current compiler run. DEFAULT
- In addition to syntax errors and warnings generated by optimization passes, outputs warnings generated by selected code-checking passes.
VERBOSE
- In addition to syntax errors and warnings generated by optimization passes, outputs warnings generated by all code-checking passes.
The
warning_level
parameter defaults to a value ofDEFAULT
.
language
The language
parameter refers to which version of
ECMAScript to assume when checking for errors in your code.
ECMASCRIPT3
- Checks code assuming ECMAScript 3 compliance, and gives errors for code using features only present in later versions of ECMAScript.
ECMASCRIPT5
- Checks code assuming ECMAScript 5 compliance, allowing new features not present in ECMAScript 3, and gives errors for code using features only present in later versions of ECMAScript.
ECMASCRIPT5_STRICT
- Like
ECMASCRIPT5
but assumes compliance with strict mode ("use strict";
). ECMASCRIPT6
- Checks code assuming ECMAScript 6 compliance, allowing new features not present in ECMAScript 5.
ECMASCRIPT6_STRICT
- Like
ECMASCRIPT6
but assumes compliance with strict mode ("use strict";
).
The language
parameter defaults to a value of ECMASCRIPT6
.
language_out
The language_out
parameter refers to which version of
ECMAScript your code will be returned in. It accepts the same options
as language
and is used to transpile between different levels of ECMAScript.
The default value is ECMASCRIPT5
.
use_types_for_optimization
The use_types_for_optimization
parameter controls whether the compiler will use
type information to optimize your code. Incorrect type information may
cause the compiler to make invalid assumptions about your code and do invalid
optimizations.
The use_types_for_optimization
parameter is false
by default.
Error Messages
If the server fails to process your request, you will receive one of the server error messages listed in the table below. Note that these server error messages are different from compiler errors and warnings. Compiler errors and warnings indicate that Closure Compiler found a problem in your JavaScript code. Server error messages indicate that the compiler is not able to process your code at all because of an error in your request.
Error Code | Error Message | Meaning |
---|---|---|
2 | Unknown output mode. | The value of
the output_format parameter is something other
than xml , json , or text . |
4 | Unknown compression level. | The
value of the compilation_level parameter is something
other
than WHITESPACE_ONLY , SIMPLE_OPTIMIZATIONS ,
or ADVANCED_OPTIMIZATIONS . |
8 | POST data too large. |
The size of the data you sent to the Closure Compiler service
exceeds 200,000 bytes. Both the Compiler Service UI and your API
calls use an HTTP POST request to communicate with the service, and
the total amount of data sent in this request cannot exceed 200,000
bytes. For API calls, this limit applies to the total amount of text
in all request parameters. For the Closure Compiler UI, this limit
applies to the total amount of text in both the source code and the
compiler options like @code_url . If your request is
too big, either move source code into separate files and reference
them using
@code_url , or use the Closure Compiler application on
your local machine.
|
9 | File too large. | The total amount of
code from all code_url files,
all externs_url files, all js_code code and
all js_externs code exceeds 1024000 bytes. |
10 | Cannot retrieve content from URL. | An error
occurred when the Closure Compiler service tried to retrieve either a JavaScript
file indicated in the code_url parameter or an externs
file indicated in the externs_url parameter. Check that
the URL is correct and that the permissions of the file allow it to be
viewed. |
12 | URL is not formed properly. | The value of either
the code_url parameter or the externs_url
parameter is not a well-formed URL. |
13 | No output information to produce, yet compilation was requested. | No output_info parameter has been
specified. |
14 | Unknown output_info value | The value of
an output_info parameter is something other
than compiled_code , warnings ,
or statistics . |
16 | Unknown warning level | The value of
the warning_level parameter is something other
than QUIET , DEFAULT ,
or VERBOSE . |
17 | Unknown formatting option. | The value of
the formatting parameter is something other
than pretty_print . |
18 | Unknown parameter in HTTP request | The HTTP request contains a parameter other than one of the ones listed in this document. |
19 | Illegal value for output_file_name | The output file name contains a character a number, letter, dot,
underscore, or dash, or it contains two consecutive dots (.. ) |
22 | Too many compiles performed recently. Try again later. | You have submitted too many compiles from your machine. After an hour, you should be able to perform compiles again. |
23 | Compiler exception (with backtrace) | The compiler crashed. The text of the error will contain information to help Google debug the problem. |
24 | Unsupported input resource type | The resource type is not http:, and so the input file will not be retrieved. |