closure-compiler

A JavaScript checker and optimizer.

7,356

1,143

7,356

909

View on GitHub View on NPM

Top Related Projects

terser

8,615

🗜 JavaScript parser, mangler and compressor toolkit for ES6+

esbuild

37,921

An extremely fast bundler for the web

babel

43,160

🐠 Babel is a compiler for writing next generation JavaScript.

A bundler for javascript and friends. Packs many modules into a few bundled assets. Code Splitting allows for loading parts of the application on demand. Through "loaders", modules can be CommonJs, AMD, ES6 modules, CSS, Images, JSON, Coffeescript, LESS, ... and your custom stuff.

rollup

25,227

Next-generation ES module bundler

parcel

43,380

The zero configuration build tool for the web. 📦🚀

Quick Overview

Google Closure Compiler is a tool for making JavaScript download and run faster. It parses, compiles, and optimizes JavaScript code, removing dead code and rewriting and minimizing what's left. The compiler can also check syntax, variable references, and types, and warn about common JavaScript pitfalls.

Pros

Significantly reduces the size of JavaScript files, improving load times
Performs advanced optimizations and dead code elimination
Provides type checking and error detection
Supports modern JavaScript features and can output to different ECMAScript versions

Cons

Steep learning curve, especially for advanced optimizations
Can be slow for large projects
May require code modifications to work optimally with the compiler
Some debugging can be challenging due to the transformed code

Code Examples

Basic usage with Node.js:

const ClosureCompiler = require('google-closure-compiler').compiler;

const closureCompiler = new ClosureCompiler({
  js: 'path/to/your/js/file.js',
  compilation_level: 'SIMPLE',
  js_output_file: 'path/to/output.js'
});

closureCompiler.run((exitCode, stdOut, stdErr) => {
  console.log('Exit code:', exitCode);
});

Using the compiler with advanced optimizations:

const ClosureCompiler = require('google-closure-compiler').compiler;

const closureCompiler = new ClosureCompiler({
  js: ['file1.js', 'file2.js'],
  compilation_level: 'ADVANCED',
  warning_level: 'VERBOSE',
  output_wrapper: '(function(){%output%}).call(this);',
  js_output_file: 'output.min.js'
});

closureCompiler.run((exitCode, stdOut, stdErr) => {
  console.log('Compilation finished');
});

Using the compiler as a gulp task:

const gulp = require('gulp');
const closureCompiler = require('google-closure-compiler').gulp();

gulp.task('compile', () => {
  return gulp.src('./src/**/*.js', {base: './'})
    .pipe(closureCompiler({
      compilation_level: 'SIMPLE',
      warning_level: 'VERBOSE',
      language_in: 'ECMASCRIPT6_STRICT',
      language_out: 'ECMASCRIPT5_STRICT',
      output_wrapper: '(function(){\n%output%\n}).call(this)',
      js_output_file: 'output.min.js'
    }))
    .pipe(gulp.dest('./dist'));
});

Getting Started

Install the Closure Compiler:

npm install --save-dev google-closure-compiler

Create a simple JavaScript file to compile:

// main.js
function hello(name) {
  console.log('Hello, ' + name + '!');
}
hello('World');

Run the compiler:

npx google-closure-compiler --js=main.js --js_output_file=output.js

Check the output in output.js. It should be a minified version of your original code.

Competitor Comparisons

terser

8,615

🗜 JavaScript parser, mangler and compressor toolkit for ES6+

Pros of Terser

Faster processing speed for most JavaScript minification tasks
Easier to set up and use, with simpler configuration options
Better support for modern JavaScript features and syntax

Cons of Terser

Less aggressive optimization compared to Closure Compiler
Limited type-checking capabilities
Fewer advanced optimization techniques for very large codebases

Code Comparison

Terser:

// Input
function add(a, b) {
  return a + b;
}
// Output
function add(n,d){return n+d}

Closure Compiler:

// Input
function add(a, b) {
  return a + b;
}
// Output
add=function(a,b){return a+b};

Both tools effectively minify the code, but Closure Compiler goes a step further by assigning the function to a variable, potentially allowing for more aggressive optimizations in larger codebases.

Terser is generally preferred for quick and straightforward minification tasks, while Closure Compiler excels in advanced optimization scenarios, especially for large-scale projects where type-checking and more aggressive code transformations are beneficial.

esbuild

37,921

An extremely fast bundler for the web

Pros of esbuild

Significantly faster build times due to its Go-based implementation
Simpler configuration and easier to set up for most projects
Built-in support for modern JavaScript features and TypeScript

Cons of esbuild

Less advanced optimization capabilities compared to Closure Compiler
Limited support for older browsers and legacy JavaScript features
Smaller ecosystem and fewer plugins available

Code Comparison

esbuild:

import esbuild from 'esbuild'

await esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  minify: true,
  outfile: 'out.js',
})

Closure Compiler:

const ClosureCompiler = require('google-closure-compiler').compiler;

new ClosureCompiler({
  js: 'app.js',
  compilation_level: 'ADVANCED',
  js_output_file: 'out.js'
}).run((exitCode, stdOut, stdErr) => {
  // Handle compilation result
});

esbuild focuses on simplicity and speed, making it easier to set up and use for most projects. It excels in build performance but may lack some advanced optimization features. Closure Compiler offers more powerful optimization capabilities and better support for older browsers, but comes with a steeper learning curve and slower build times. The choice between the two depends on project requirements, with esbuild being more suitable for modern web applications and Closure Compiler for projects requiring extensive optimization and legacy browser support.

babel

43,160

🐠 Babel is a compiler for writing next generation JavaScript.

Pros of Babel

More flexible and extensible with a plugin-based architecture
Supports latest ECMAScript features and proposals
Wider community support and ecosystem

Cons of Babel

Generally slower compilation times
Larger output file sizes
Less aggressive optimization compared to Closure Compiler

Code Comparison

Babel:

// Input
const square = (n) => n * n;

// Output
var square = function square(n) {
  return n * n;
};

Closure Compiler:

// Input
const square = (n) => n * n;

// Output (Advanced mode)
var a=function(b){return b*b};

Key Differences

Babel focuses on transpiling modern JavaScript to older versions, while Closure Compiler emphasizes optimization and minification. Babel is more popular for general-purpose development, whereas Closure Compiler is often used for production builds in large-scale applications.

Babel offers a more modular approach with its plugin system, allowing developers to customize the transformation process. Closure Compiler provides more aggressive optimization, resulting in smaller file sizes but potentially less readable code.

Both tools have their strengths, and the choice between them depends on project requirements, performance needs, and development workflow preferences.

webpack

64,559

Pros of webpack

More flexible and modular, supporting a wide range of asset types beyond just JavaScript
Extensive plugin ecosystem for customization and additional functionality
Built-in development server with hot module replacement for faster development

Cons of webpack

Can be more complex to configure, especially for larger projects
May produce larger bundle sizes without careful optimization
Slower compilation times compared to Closure Compiler for very large projects

Code Comparison

Webpack configuration:

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  }
};

Closure Compiler usage:

java -jar compiler.jar --js_output_file=out.js in1.js in2.js in3.js

Summary

webpack offers more flexibility and a rich ecosystem but can be more complex to set up. Closure Compiler provides powerful optimization but is more focused on JavaScript compilation. The choice between them depends on project requirements, with webpack being more suitable for modern web applications with diverse asset types, while Closure Compiler excels in pure JavaScript optimization scenarios.

rollup

25,227

Next-generation ES module bundler

Pros of Rollup

Simpler configuration and easier to use for modern JavaScript projects
Better support for ES modules and tree-shaking
Faster build times for smaller to medium-sized projects

Cons of Rollup

Less powerful optimization capabilities compared to Closure Compiler
Limited support for older JavaScript syntax and browser compatibility
Smaller ecosystem and fewer plugins available

Code Comparison

Rollup configuration:

export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'iife'
  }
};

Closure Compiler usage:

java -jar compiler.jar --js_output_file=out.js \
  --compilation_level ADVANCED_OPTIMIZATIONS \
  --js src/file1.js \
  --js src/file2.js

Summary

Rollup is a more modern and streamlined bundler, ideal for projects using ES modules and targeting newer browsers. It offers simpler configuration and faster builds for smaller projects. Closure Compiler, on the other hand, provides more advanced optimization capabilities and better support for older JavaScript syntax, making it suitable for complex projects requiring extensive code optimization and broad browser compatibility. The choice between the two depends on project requirements, target environment, and desired level of optimization.

parcel

43,380

The zero configuration build tool for the web. 📦🚀

Pros of Parcel

Zero configuration required, making it easier to set up and use
Faster build times due to its multi-core processing capabilities
Built-in support for various file types and assets without additional plugins

Cons of Parcel

Less fine-grained control over optimization compared to Closure Compiler
May produce larger bundle sizes for complex applications
Limited customization options for advanced use cases

Code Comparison

Parcel:

// No configuration needed, just run:
parcel index.html

Closure Compiler:

// Requires configuration and command-line options:
java -jar closure-compiler.jar --js input.js --js_output_file output.js

Parcel focuses on simplicity and ease of use, requiring minimal setup for most projects. It automatically handles many common tasks without configuration. Closure Compiler, on the other hand, provides more advanced optimization techniques and greater control over the compilation process, but requires more setup and configuration.

Parcel is ideal for quick prototyping and smaller projects, while Closure Compiler excels in large-scale production environments where fine-tuned optimization is crucial for performance. The choice between the two depends on project requirements, team expertise, and desired level of control over the build process.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Google Closure Compiler

The Closure Compiler is a tool for making JavaScript download and run faster. It is a true compiler for JavaScript. Instead of compiling from a source language to machine code, it compiles from JavaScript to better JavaScript. It parses your JavaScript, analyzes it, removes dead code and rewrites and minimizes what's left. It also checks syntax, variable references, and types, and warns about common JavaScript pitfalls.

Important Caveats

Compilation modes other than ADVANCED were always an afterthought and we have deprecated those modes. We believe that other tools perform comparably for non-ADVANCED modes and are better integrated into the broader JS ecosystem.
Closure Compiler is not suitable for arbitrary JavaScript. For ADVANCED mode to generate working JavaScript, the input JS code must be written with closure-compiler in mind.
Closure Compiler is a "whole world" optimizer. It expects to directly see or at least receive information about every possible use of every global or exported variable and every property name.

It will aggressively remove and rename variables and properties in order to make the output code as small as possible. This will result in broken output JS, if uses of global variables or properties are hidden from it.

Although one can write custom externs files to tell the compiler to leave some names unchanged so they can safely be accessed by code that is not part of the compilation, this is often tedious to maintain.
Closure Compiler property renaming requires you to consistently access a property with either obj[p] or obj.propName, but not both.

When you access a property with square brackets (e.g. obj[p]) or using some other indirect method like let {p} = obj; this hides the literal name of the property being referenced from the compiler. It cannot know if obj.propName is referring to the same property as obj[p]. In some cases it will notice this problem and stop the compilation with an error. In other cases it will rename propName to something shorter, without noticing this problem, resulting in broken output JS code.
Closure Compiler aggressively inlines global variables and flattens chains of property names on global variables (e.g. myFoo.some.sub.property -> myFoo$some$sub$property), to make reasoning about them easier for detecting unused code.

It tries to either back off from doing this or halt with an error when doing it will generate broken JS output, but there are cases where it will fail to recognize the problem and simply generate broken JS without warning. This is much more likely to happen in code that was not explicitly written with Closure Compiler in mind.
Closure compiler and the externs it uses by default assume that the target environment is a web browser window.

WebWorkers are supported also, but the compiler will likely fail to warn you if you try to use features that aren't actually available to a WebWorker.

Some externs files and features have been added to Closure Compiler to support the NodeJS environment, but they are not actively supported and never worked very well.
JavaScript that does not use the goog.module() and goog.require() from base.js to declare and use modules is not well supported.

The ECMAScript import and export syntax did not exist until 2015. Closure compiler and closure-library developed their own means for declaring and using modules, and this remains the only well supported way of defining modules.

The compiler does implement some understanding of ECMAScript modules, but changing Google's projects to use the newer syntax has never offered a benefit that was worth the cost of the change. Google's TypeScript code uses ECMAScript modules, but they are converted to goog.module() syntax before closure-compiler sees them. So, effectively the ECMAScript modules support is unused within Google. This means we are unlikely to notice or fix bugs in the support for ECMAScript modules.

Support for CommonJS modules as input was added in the past, but is not used within Google, and is likely to be entirely removed sometime in 2024.

Supported uses

Closure Compiler is used by Google projects to:

Drastically reduce the code size of very large JavaScript applications
Check the JS code for errors and for conformance to general and/or project-specific best practices.
Define user-visible messages in a way that makes it possible to replace them with translated versions to create localized versions of an application.
Transpile newer JS features into a form that will run on browsers that lack support for those features.
Break the output application into chunks that may be individually loaded as needed.

NOTE: These chunks are plain JavaScript scripts. They do not use the ECMAScript import and export syntax.

To achieve these goals closure compiler places many restrictions on its input:

Use goog.module() and goog.require() to declare and use modules.

Support for the import and export syntax added in ES6 is not actively maintained.
Use annotations in comments to declare type information and provide information the compiler needs to avoid breaking some code patterns (e.g. @nocollapse and @noinline).
Either use only dot-access (e.g. object.property) or only use dynamic access (e.g. object[propertyName] or Object.keys(object)) to access the properties of a particular object type.

Mixing these will hide some uses of a property from the compiler, resulting in broken output code when it renames the property.
In general the compiler expects to see an entire application as a single compilation. Interfaces must be carefully and explicitly constructed in order to allow interoperation with code outside of the compilation unit.

The compiler assumes it can see all uses of all variables and properties and will freely rename them or remove them if they appear unused.
Use externs files to inform the compiler of any variables or properties that it must not remove or rename.

There are default externs files declaring the standard JS and DOM global APIs. More externs files are necessary if you are using less common APIs or expect some external JavaScript code to access an API in the code you are compiling.

Getting Started

The easiest way to install the compiler is with NPM or Yarn:

yarn global add google-closure-compiler
# OR
npm i -g google-closure-compiler

The package manager will link the binary for you, and you can access the compiler with:

google-closure-compiler

This starts the compiler in interactive mode. Type:

var x = 17 + 25;

Hit Enter, then Ctrl+Z (on Windows) or Ctrl+D (on Mac/Linux), then Enter again. The Compiler will respond with the compiled output (using SIMPLE mode by default):

var x=42;

Downloading from Maven Repository

A pre-compiled release of the compiler is also available via Maven.

Basic usage

The Closure Compiler has many options for reading input from a file, writing output to a file, checking your code, and running optimizations. Here is a simple example of compressing a JS program:

google-closure-compiler --js file.js --js_output_file file.out.js

We get the most benefit from the compiler if we give it all of our source code (see Compiling Multiple Scripts), which allows us to use ADVANCED optimizations:

google-closure-compiler -O ADVANCED rollup.js --js_output_file rollup.min.js

NOTE: The output below is just an example and not kept up-to-date. The Flags and Options wiki page is updated during each release.

To see all of the compiler's options, type:

google-closure-compiler --help

`--flag`	Description
`--compilation_level (-O)`	Specifies the compilation level to use. Options: `BUNDLE`, `WHITESPACE_ONLY`, `SIMPLE` (default), `ADVANCED`
`--env`	Determines the set of builtin externs to load. Options: `BROWSER`, `CUSTOM`. Defaults to `BROWSER`.
`--externs`	The file containing JavaScript externs. You may specify multiple
`--js`	The JavaScript filename. You may specify multiple. The flag name is optional, because args are interpreted as files by default. You may also use minimatch-style glob patterns. For example, use `--js='.js' --js='!_test.js'` to recursively include all js files that do not end in `_test.js`
`--js_output_file`	Primary output filename. If not specified, output is written to stdout.
`--language_in`	Sets the language spec to which input sources should conform. Options: `ECMASCRIPT3`, `ECMASCRIPT5`, `ECMASCRIPT5_STRICT`, `ECMASCRIPT_2015`, `ECMASCRIPT_2016`, `ECMASCRIPT_2017`, `ECMASCRIPT_2018`, `ECMASCRIPT_2019`, `STABLE`, `ECMASCRIPT_NEXT`
`--language_out`	Sets the language spec to which output should conform. Options: `ECMASCRIPT3`, `ECMASCRIPT5`, `ECMASCRIPT5_STRICT`, `ECMASCRIPT_2015`, `ECMASCRIPT_2016`, `ECMASCRIPT_2017`, `ECMASCRIPT_2018`, `ECMASCRIPT_2019`, `STABLE`
`--warning_level (-W)`	Specifies the warning level to use. Options: `QUIET`, `DEFAULT`, `VERBOSE`

See the Google Developers Site for documentation including instructions for running the compiler from the command line.

NodeJS API

You can access the compiler in a JS program by importing google-closure-compiler:

import closureCompiler from 'google-closure-compiler';
const { compiler } = closureCompiler;

new compiler({
  js: 'file-one.js',
  compilation_level: 'ADVANCED'
});

This package will provide programmatic access to the native Graal binary in most cases, and will fall back to the Java version otherwise.

Please see the closure-compiler-npm repository for documentation on accessing the compiler in JS.

Compiling Multiple Scripts

If you have multiple scripts, you should compile them all together with one compile command.

google-closure-compiler in1.js in2.js in3.js --js_output_file out.js

You can also use minimatch-style globs.

# Recursively include all js files in subdirs
google-closure-compiler 'src/**.js' --js_output_file out.js

# Recursively include all js files in subdirs, excluding test files.
# Use single-quotes, so that bash doesn't try to expand the '!'
google-closure-compiler 'src/**.js' '!**_test.js' --js_output_file out.js

The Closure Compiler will concatenate the files in the order they're passed at the command line.

If you're using globs or many files, you may start to run into problems with managing dependencies between scripts. In this case, you should use the included lib/base.js that provides functions for enforcing dependencies between scripts (namely goog.module and goog.require). Closure Compiler will re-order the inputs automatically.

Closure JavaScript Library

The Closure Compiler releases with lib/base.js that provides JavaScript functions and variables that serve as primitives enabling certain features of the Closure Compiler. This file is a derivative of the identically named base.js in the soon-to-be deprecated Closure Library. This base.js will be supported by Closure Compiler going forward and may receive new features. It was designed to only retain its perceived core parts.

Getting Help

Post in the Closure Compiler Discuss Group.
Ask a question on Stack Overflow.
Consult the FAQ.

Building the Compiler

To build the compiler yourself, you will need the following:

Prerequisite	Description
Java 11 or later	Used to compile the compiler's source code.
NodeJS	Used to generate resources used by Java compilation
Git	Used by Bazel to download dependencies.
Bazelisk	Used to build the various compiler targets.

Installing Bazelisk

Bazelisk is a wrapper around Bazel that dynamically loads the appropriate version of Bazel for a given repository. Using it prevents spurious errors that result from using the wrong version of Bazel to build the compiler, as well as makes it easy to use different Bazel versions for other projects.

Bazelisk is available through many package managers. Feel free to use whichever you're most comfortable with.

Instructions for installing Bazelisk.

Building from a terminal

$ bazelisk build //:compiler_uberjar_deploy.jar
# OR to build everything
$ bazelisk build //:all

Testing from a terminal

Tests can be executed in a similar way. The following command will run all tests in the repo.

$ bazelisk test //:all

There are hundreds of individual test targets, so it will take a few minutes to run all of them. While developing, it's usually better to specify the exact tests you're interested in.

bazelisk test //:$path_to_test_file

Building from an IDE

See Bazel IDE Integrations.

Running

Once the compiler has been built, the compiled JAR will be in the bazel-bin/ directory. You can access it with a call to java -jar ... or by using the package.json script:

# java -jar bazel-bin/compiler_uberjar_deploy.jar [...args]
yarn compile [...args]

Running using Eclipse

Open the class src/com/google/javascript/jscomp/CommandLineRunner.java or create your own extended version of the class.
Run the class in Eclipse.
See the instructions above on how to use the interactive mode - but beware of the bug regarding passing "End of Transmission" in the Eclipse console.

Contributing

Contributor code of conduct

However you choose to contribute, please abide by our code of conduct to keep our community a healthy and welcoming place.

Reporting a bug

First make sure that it is really a bug and not simply the way that Closure Compiler works (especially true for ADVANCED_OPTIMIZATIONS).
- Check the official documentation
- Consult the FAQ
- Search on Stack Overflow and in the Closure Compiler Discuss Group
- Look through the list of compiler assumptions.
If you still think you have found a bug, make sure someone hasn't already reported it. See the list of known issues.
If it hasn't been reported yet, post a new issue. Make sure to add enough detail so that the bug can be recreated. The smaller the reproduction code, the better.

Suggesting a feature

Consult the FAQ to make sure that the behaviour you would like isn't specifically excluded (such as string inlining).
Make sure someone hasn't requested the same thing. See the list of known issues.
Read up on what type of feature requests are accepted.
Submit your request as an issue.

Submitting patches

All contributors must sign a contributor license agreement (CLA). A CLA basically says that you own the rights to any code you contribute, and that you give us permission to use that code in Closure Compiler. You maintain the copyright on that code. If you own all the rights to your code, you can fill out an individual CLA. If your employer has any rights to your code, then they also need to fill out a corporate CLA. If you don't know if your employer has any rights to your code, you should ask before signing anything. By default, anyone with an @google.com email address already has a CLA signed for them.
To make sure your changes are of the type that will be accepted, ask about your patch on the Closure Compiler Discuss Group
Fork the repository.
Make your changes. Check out our coding conventions for details on making sure your code is in correct style.
Submit a pull request for your changes. A project developer will review your work and then merge your request into the project.