Polymer & Closure Compiler in Gulp

Hello! This is an adjunct article 🎥 to a talk I gave 🗣️ at the Polymer Summit London, in October 2016. It describes how to add Closure Compiler to the build steps of a Polymer project.

at the Polymer Summit London

Wait, what?

Google’s Closure Compiler is a JavaScript optimizer, typechecker and minifier. It also transpiles modern JS into ES5. It can make you more productive by providing typechecking, static analysis, and a warm fuzzy feeling that a robot has read and validated your code 👍

Polymer, on the other hand, is a library that helps you build modern HTML web experiences with Web Components — specifically, reusable custom elements. There’s also a vast library of elements available already 🎉

Closure Compiler and Polymer are great together. You can write Polymer that is compiled, giving you almost immediate compile-time feedback—are your types correct? — and reducing your code size. You’ll also be able to use use all that modern JS hotness 🔥, regardless of which browser you’re targeting.

The Final Product

If you’d like to check out the final product, a working sample app with a single Polymer element — head over to GitHub. But if you’d like to work through the steps, read on! 📕

Your First Build

Let’s assume that you have no build steps. None! Well, maybe you use vulcanize, to bring together your custom elements. Let’s assume you have an index file like this, containing your elements —

<link rel="import" href="elements/my-element.html">
<link rel="import" href="elements/my-other-element.html">

Get the dependencies

For this task, we’ll use Gulp, and the JavaScript version of Closure Compiler. Start by installing dependencies —

$ npm install --save-dev gulp gulp-vulcanize gulp-crisper google-closure-compiler-js

#1: Merge and split your code

Let’s create or update your Gulp configuration file to merge together your elements (it’s called gulpfile.js). This vulcanizes your code, bringing it all together: it then uses crisper to split just the HTML and JS apart.

Step #1: Merge and split

Note that we don’t include the Polymer source code itself — it’s explicitly excluded. This is because Polymer, at least in the 1.x branch, does not compile well with Closure Compiler. You shouldn’t worry though —the point here is to typecheck your code, not Polymer itself.

#2: Compile the JS

Now, we just need one more step to compile your elements. At the bottom of your Gulp configuration file, add this compile step. This depends on your previous merge step, and produces a minified output file.

Step #2: Compile

It has a few nuances. We need to load the Polymer externs manually, as Closure Compiler does not include them by default. You’ll also need to set polymerPass to true, and provide some sensible defaults.

Now, run gulp compile in a terminal. If your Polymer code is perfect — don’t worry, no-one’s is to begin with — you won’t see any warnings.

#3 (optional): Additional reading

If you’d like to speed up your builds, there’s also a Java version of Closure Compiler. And if you’d like to decrease your code size and increase performance, Closure Compiler also has an ADVANCED mode. However, most Polymer elements won’t compile ⚠️ without changes. To find out more, read Using Polymer with Closure Compiler.

#4: Use the output

You’re almost done! To quickly see your work in an actual browser, you can create a HTML file which includes all four dependencies —the Web Components polyfill, Polymer itself, your vulcanized HTML, and your minified, compiled, transpiled JavaScript 👏

<!-- Order is important! -->
<script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
<link rel="import" href="bower_components/polymer/polymer.html"><link rel="import" href="dest/elements.html">
<script src="dest/elements.min.js"></script>

Rather than four dependencies, you could also add an extra Gulp task which merges the JS or HTML together (especially if you don’t want to ship your bower_components directory). Don’t try to compile again at this point — just concatenating the files together works fine.


You’ve compiled your elements, and gained an awesome 👑 static compile step. Go reward yourself with a donut! 🍩