About a year ago in May 2013, Google launched Polymer.js.

So here we are, a year later. And the question is: Is it yet ready for prime time? Is it yet possible to create a production ready application using Polymer web development techniques?

To answer this question, I took Polymer out for a test drive to develop a web application and to see how well it would behave. This article is about that experience and what I learned in the process.

Polymer.js: The Concept

Before we get into our Polymer tutorial, let’s first define Polymer.js, not for what it claims to be, but for what it actually is.

When you begin to check out Polymer, you can’t help but immediately be intrigued by its self-professed unique world view. Polymer purports itself as taking a sort of back-to-nature approach that “puts elements back at the center of web development”. With Polymer.js, you can craft your own HTML elements and compose them into complete, complex web applications that are scalable and maintainable. It’s all about creating new (i.e., custom) elements that can then be reused in your HTML pages in a declarative way, without needing to know or understand their internals.

Elements, after all, are the building blocks of the web. Accordingly, Polymer’s weltanschauung is that web development should fundamentally be based on extending the existing element paradigm to build more powerful web components, rather than replacing markup with “gobs of script” (to use their words). Stated another way, Polymer believes in leveraging the browser’s “native” technologies rather than relying on an increasingly complex labyrinth of custom JavaScript libraries (jQuery et. al.). An intriguing notion indeed.

OK, so that’s the theory. Now let’s take a look at the reality.

Polymer Web Development: The Reality

While Polymer’s philosophical approach certainly has merit, it is unfortunately an idea that (at least to some extent) is ahead of its time.

Polymer.js places a hefty set of requirements on the browser, relying on a number of technologies that are in still in the process of standardization (by W3C) and are not yet present in today’s browsers. Examples include the shadow dom, template elements, custom elements, HTML imports, mutation observers, model-driven views, pointer events, and web animations. These are marvelous technologies, but at least as of now, that are yet-to-come to modern browsers.

The Polymer strategy is to have front-end developers leverage these leading-edge, still-to-come, browser-based technologies, which are currently in the process of standardization (by W3C), as they become available. In the meantime, in order to fill the gap, Polymer suggests the use of polyfills (downloadable JavaScript code which provides features that are not yet built into today’s browsers). The recommended polyfills are designed in such a way that (at least theoretically) will be seamless to replace once the native browser versions of these capabilities become available.

OK, fine. But let me get this straight. At least for now, we’re going to use JavaScript libraries (i.e., polyfills) to avoid the use of JavaScript Libraries? Well, that’s “fascinating”.

The bottom line, then, is that we’re in a sort of limbo mode with Polymer, as it is ultimately relying on (or perhaps more accurately, approximating) browser technologies that don’t yet exist. Accordingly, Polymer.js today seems more like a study in how element-centric applications may be built in the future (i.e., when all the necessary features are implemented in the major browsers and polyfills are no longer needed). But, at least at present, Polymer seems more like an intriguing concept than an actual option for creating robust change-your-view-of-the-world applications right here and now, which makes writing (or finding) a Polymer tutorial difficult outside of Google’s documentation.

Polymer Architecture

Now, onto our guide. Polymer.js is architecturally divided into four layers:

Native: Needed features currently available natively in all major browsers. Foundation: Polyfills that implement needed browser features not yet natively available in the browsers themselves. (The intention is for this layer to disappear over time as the capabilities it provides become available natively in the browser.). Core: The necessary infrastructure for Polymer elements to exploit the capabilities provided by the Native and Foundation layers.. Elements: A basic set of elements, intended to serve as building blocks that can help you create your application. Includes elements that provide: Basic functionality like ajax, animation, flex layout, and gestures. Encapsulation of complicated browser APIs and CSS layouts. UI component renderers such as accordions, cards, and sidebars.

Creating a Polymer Application

To get started, there are some articles and tutorial write-ups that help introduce you to Polymer, its concepts, and its structure. But if you’re anything like me, when you’ve gone through them and are ready to actually build your application, you quickly realize that you’re really not quite sure where to start or how to create it. Since I’ve now gone through the process and figured it out, here are some pointers…

Polymer web development is all about creating elements, and is only about creating elements. So, consistent with the Polymer world view, our application is going to be… a new element. Nothing more and nothing less. Oh OK, I get it. So that’s where we start.

For our Polymer project example, I’ll name the top-level element of the application , since custom element names (regardless of what framework you use to create them) must include a hyphen (e.g., x-tags, polymer-elements, etc.).

The next step, though, requires quite a bit more thought. We need to decide on how we are going to componentize our application. An easy approach is just to try to identify, from a visual perspective, the components in our application and then try to create them as custom elements in Polymer.

So for example, imagine that we have an app with the following screens:

We can identify that the top bar and the side bar menu are not going to change and the actual “content” of the app could load different “views”.

That being the case, one reasonable approach would be to create the element for our app and, inside that element, we could use some Polymer UI Elements to create the top bar and the side bar menu.

We can then create our two main views, which we’ll call ListView and the SingleView, to be loaded into the “content” area. For the items in the ListView, we can create an ItemView.

This will then yield a structure something like this:

The Good News

Now that we have our example Polymer application, we can insert it into any web page just by importing our “toptal-app.html” and adding the tag because, after all, our app is just an element. That’s cool.

In fact, therein does lie much of the power and beauty of the Polymer paradigm. The custom elements you create for your application (including the top-level one for your entire application) are treated as any other element in a web page. You can therefore access their properties and methods from any other JavaScript code or library (e.g., Backbone.js, Angular.js, etc.). You can even use those libraries to create your own new elements.

Moreover, your custom components are compatible with other custom element libraries (such as Mozilla’s X-Tag). So it doesn’t matter what you use to create your own custom element, it is compatible with Polymer and any other browser technology.

It’s therefore not surprising that we’ve already started to see the advent of a community of Element Creators that expose and share their newly created elements in forums like the Custom Elements site. You can go there and grab whatever component you need and just use it in your application.

On the other hand…

Polymer is still sufficiently new technology that developers, especially novice app developers, are likely to find it to be somewhat brittle, with a number of not-so-hard-to-find rough edges.

Here’s a sampling:

Lack of documentation and guidance. Not all Polymer.js UI and non-UI Elements are documented. Sometimes the only “guidance” on how to use them is demo code. In some cases, it’s even necessary to refer to the source code of a Polymer Element to understand better how it works and can/should be used. It’s not entirely clear how to organize larger applications. In particular, how are you supposed to pass singleton objects between elements? Which strategy should you employ to test your custom elements? Guidance on these types of issues at this point is scant at best.

Dependency errors and version-itis. Even when you download Polymer.js elements as is recommended, you might find yourself with a dependency error, pointing to different version dependencies in the same element. While it is understood that Polymer Elements are currently under heavy development, these kind of problems can make development quite challenging, eroding developer confidence and interest.

Problems on mobile platforms. Polymer.js performance on mobile platforms can often be somewhere between frustrating and problematic. Downloading the entire library and polyfills (without gzip’ing) is slow, and you need to download every Polymer Element that you intend to use. Processing the polyfills, libraries, and custom elements appears to be an expensive task on mobile platforms. Even when the downloading is complete, you still often have a blank screen for a few seconds. Especially for more complex functionality (such as drag-and-drop or rendering into a canvas), you may find that functionality that works fine on the desktop simply does not work properly, or is not yet supported, on the mobile platform. In my particular case, one such frustration that I encountered was with rendering into a canvas on iOS.

Polymer.js performance on mobile platforms can often be somewhere between frustrating and problematic. Inadequate or confusing error reporting. Sometimes when you misspell an attribute name, or just break something related to the core layer itself, you receive a strange error message on your console with two call stacks that you need to investigate to try determine where the problem is. Sometimes it’s easy to solve this, but sometimes you end up needing to try a completely different strategy just to avoid the error since you can’t track down it’s source.

Conclusion

Polymer is intriguing technology, but it is undeniably still in its infancy. As such, it’s not yet well suited to development of a large, enterprise level, production-ready application. Additionally, there aren’t many guides or tutorials available specific to Polymer.js web development.

As far as whether the JavaScript-centric or DOM-centric approach is really fundamentally better, the jury is still out. Polymer makes some convincing arguments, but counter-arguments do exist.

Perhaps most notably, Polymer requires a fairly significant level of expertise in using browser technologies like the DOM. You’re in many ways returning to the days before jQuery, learning the DOM API to do simple tasks like adding or removing a CSS class from an element. This certainly does make it feel, at least on some level, like you’re taking a step backward rather than forward.

But that said, it does appear likely that custom elements are going to be an important part of Web Development in the future, so diving in sooner rather than later would probably be prudent for today’s web developer. And if you’ve never tried to create your own custom elements before, Polymer (and this tutorial) is probably a sensible place to start.