Tips for Upgrading to Polymer 2.0: Imports & Hybrid Mode

Contents

Introduction

Polymer 2.0 is fantastic and the upgrade path from v1.0 has been well planned and implemented so it’s pretty smooth going and there are some great docs that explain the upgrade process to follow.

But there are still a few “gotchas” that might catch you out along the way and I think some are down to the fact that the upgrade process is so good, sometimes it’s easy to forget that between two elements in the project you’re switching entirely to the new API.

So, here are some things to remember when upgrading …

One reason why the upgrade path to 2.0 is so simple is that the new version includes a compatibility layer to support the old API. This is loaded when your elements import polymer using the traditional import URL we’re familiar with:

<link rel="import" href="../bower_components/polymer/polymer.html">

This means that you can very often load an element that was written against v1.x and, as long as it’s used the latest syntax it should just run with few or no changes.

To do this it pulls in the 2.0 runtime plus a compatibility layer to support the older 1.x element syntax and API. When this happens, you’re running in “hybrid mode”. You have Polymer 2.0 runtime but Polymer 1.x style code.

This is great for the first part of the upgrade process and, I suspect, is what the vast majority of applications will be using while the common Polymer supplied iron- and paper- elements are themselves in hybrid mode. Remember, you need to make sure that all your package manager references are to the “#2.0-preview” branches!

You can’t really “turn off” hybrid mode - it stops loading the compatibility layer once everything stops referencing it.

At some point though you will want to start writing your new components in 2.0 style ES6 in preparation for being able to run just the 2.0 runtime which, without the compatibility layer, is much smaller.

To do this you now import the Polymer element:

<link rel="import" href="../bower_components/polymer/polymer-element.html">

This now pulls in a much smaller set of dependencies. One of the things that will help make 2.0 more compact is that the Polymer runtime itself is broken down and more granular (this was tried to some degree with 1.x with the mini / micro / full imports that didn’t really gain traction).

With 1.x, you had the whole API automatically available, but now with 2.0 you can cherry-pick and pull in just what your element needs which, when combined with lazy loading and other serving options, will make startup times faster.

And this is the first “gotcha” that I think most people face. You now need to import the additional non-core features you need in order to use them.

The one that catches me out the most is using on-tap (instead of on-click). This is part of the Gestures feature so if your on-tap isn’t working, chances are you forgot to add the import for it in your element:

<link rel="import" href="../bower_components/polymer/lib/mixins/gesture-event-listeners.html">

There are also others - the async and debounce features that were “just there” as part of 1.x are now separated out and need to be pulled in and the syntax is different too. The old syntax only works for older 1.x style code that is referencing what is now the hybrid-mode compatibility import.

For debounce, you will need:

<link rel="import" href="../bower_components/polymer/lib/utils/debounce.html">

Your debounce code will look more like this:

this._debouncer = Polymer.Debouncer.debounce(
  this._debouncer,
  Polymer.Async.timeOut.after(60),
  debouncedFunction);

The debounce import itself pulls in the Async module, if you need to use that directly then you would import it in a similar way:

<link rel="import" href="../bower_components/polymer/lib/utils/async.html">

It has more timing options available than before - microtask, setTimeout, requestAnimationFrame and requestIdleCallback.

So, if something doesn’t seem to be working, always check that when you’re using 2.0 directly that you have imported the dependencies you’re trying to use. It’s also well-worth reading through the Polymer 2.0 documentation and upgrading guides at least twice as well as browsing through the API reference and lib section of the GitHub Repo to see what things are available and where.

And remember to run polymer lint regularly which can help you avoid some mistakes.