Getting started with Polymer 3.0

4 min readAug 24, 2017

The Polymer library provides a set of features for creating custom elements. These features are designed to make it easier and faster to make custom elements that work like standard DOM elements. Similar to standard DOM elements, Polymer elements can be:

Instantiated using a constructor or document.createElement.
Configured using attributes or properties.
Populated with internal DOM inside each instance.
Responsive to property and attribute changes.
Styled with internal defaults or externally.
Responsive to methods that manipulate its internal state.

Polymer team has not yet confirmed the stable release as they mentioned its an experimental version in their blog

“ Polymer 3.0 preview is available to experiment with, and today’s installment will get you started. But note that we use the word “experiment” advisedly. This is a very early preview, and there are definitely rough edges aplenty.”

Now you can start working with polymer with your favorite tools like NPM package manager like npm , yarn and modules using ES6.

Installation

To get started you have to update your polymer CLI

npm install -g polymer-cli

You’ll also need to install the Yarn package manager to install components .See the Yarn installation page for instructions.

Now to check preview you need to have chrome 61 or latest safari since they have polyfill support in the browser.

Install dependencies with Yarn

In npm the polymer components are published under namespace@polymer

Initialize the project:

yarn init

Edit the generated package.json file and add the "flat": true property.

{
  "name": "my-app",
  "flat": true,
  ...

Install components using yarn add, which is equivalent to bower install --save. For example:

yarn add @polymer/polymer@next
yarn add @webcomponents/webcomponentsjs

Import dependencies

You can import a module in HTML using <script type="module">. For example, your index.html might look like this:

<!doctype html>
<html>
  <head>
    <!-- Load polyfills. Same as 2.x, except for the path -->
    <script
        src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js">
    </script>

    <!-- Import the my-app element's module. -->
    <script type="module" src="src/my-app.js"></script>
  </head>
  <body>
    <my-app></my-app>
  </body>
</html>

From inside a module, you can import a module using the import statement:

import {Element as PolymerElement}
    from "../node_modules/@polymer/polymer/polymer-element.js"

As with Bower dependencies, reusable elements should not include the node_modules in the path (for example ../@polymer/polymer/polymer-element.js).

There are a few important things to note about modules and the import statement:

Like HTML imports, the import must use a path, not a module name.
The imported path must start with “./", "../", or "/".
The import statement can only be used inside a module (that is, an external file or inline script loaded with <script type="module">.
Modules always run in strict mode.

There are several forms of the import statement. For the most part, elements modules register an element but don’t export any symbols, so you can use this simple import statement:

import "../@polymer/paper-button/paper-button.js"

For behaviors, you’ll typically import the behavior explicitly:

import {IronResizableBehavior}
    from "../@polymer/iron-resizable-behavior/iron-resizable-behavior.js"

For utility modules like Async that export several members, you can import individual members, or import the entire module:

import * as Async from "../@polymer/polymer/lib/utils/async.js"Async.microTask.run(callback);

Different module are structured differently; until we have a API docs for 3.0, you may need to look at the source code to figure out what a given module exports.

Defining elements

Instead of defining elements in HTML Imports, you’ll define elements in ES6 modules. Aside from the obvious difference that you’re writing a JavaScript file instead of an HTML file, there are three major differences in the new format:

Imports use ES6 import syntax, not <link rel="import">.
Templates are defined by providing a template getter that returns a string—not the <dom-module> and <template> elements.
Instead of defining globals (for example, when defining behaviors or mixins) use the export statement to export symbols from modules.

For example:

my-app.js

// Element is the same as Polymer.Element in 2.x
// Modules give you the freedom to rename the members that you import
import {Element as PolymerElement}
    from '../node_modules/@polymer/polymer/polymer-element.js';

// Added "export" to export the MyApp symbol from the module
export class MyApp extends PolymerElement {

  // Define a string template instead of a `<template>` element.
  static get template() {
    return `<div>This is my [[name]] app.</div>`
  }

  constructor() {
    super();
    this.name = '3.0 preview';
  }

  // properties, observers, etc. are identical to 2.x
  static get properties() {
    name: {
      Type: String
    }
  }
}

customElements.define('my-app', MyApp);

As you can see, except for the changes noted above, the element definition looks the same as 2.x. So far there are only a handful of changes to the 2.x API, all related to dynamic imports: in particular, the Polymer.importHref function is no longer supported; this is slated to be replaced by dynamic ES6 imports.

For a reusable element, the import for the Polymer Element class would omit the node_modules folder:

import {Element as PolymerElement}
    from '../@polymer/polymer/polymer-element.js';

Run the project

polymer serve --npm
polymer test --npm