Polymer 3.0 预览版上手

Updated instructions available. If you're using the latest Polymer 3.0 preview
(3.0.0-pre.12 or later), see the new blog post.
The instructions in this post only apply to 3.0.0-pre.11 and earlier.

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.

But fortune favors the bold—so let's press on.

Get the tools

Before you start, you'll want to update to the latest version of Polymer CLI.

Any components you previously installed from the Polymer or PolymerElements organization using Bower you can now install from the @polymer namespace. Be sure to include the @next version to pick up the 3.0 preview packages.
You can install the polyfills from @wecomponents/webcomponentsjs (no @next required here,
since you're using the released version of the polyfills).

Alternate yarn setups

If you have other npm dependencies, such as servers, dev tools, or compilers, installing all
dependencies flat may cause version conflicts. In that case, you have several options:

Explicitly install web components with --flat.

Leave the "flat": true out of the package.json file, and add the --flat flag when
adding front-end components.

yarnadd--flat @polymer/polymer@next

For an existing project with a package.json file, this approach is probably less disruptive.

This has the advantage of keeping all dependencies in a single node_modules folder, but means
that you need to remember the --flat flag every time you add a component.

Use separate directories.

Another alternative is to set up the package.json file in the project directory with "flat": true and
add a subdirectory (for example, tools) with its own package.json for packages that need nested
dependencies.

Use modules

There's a lot to learn about ES6 modules if you aren't familiar with them, and this post will only touch on some of the key features.

If you're looking for a thorough background in ES6 modules, you might want to read this chapter on modules from Exploring ES6 by Dr. Axel Rauschmayer.

You can also watch Sam Thorogood's talk about ES6 modules from Polymer Summit.

Import dependencies

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

The current Polymer CLI tools don't support transforming dynamic imports, so you won't be able to use lazy-loading patterns like PRPL in 3.0 just yet. Before the production release, we'll be working on adding support for dynamic imports to the Polymer CLI and related tools.

If you're using a custom build setup using a tool like Webpack, you may be able to use dynamic imports today, but that's outside the scope of today's post.

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.

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:

Previewing projects

The flag tells the devserver to load components from node_modules instead of bower_components, and to look for the package name in package.json instead of bower.json.

Make sure you're loading your projects in Safari 10.1 or Chrome 61 or later. The CLI doesn't do any
conversion of modules at this point, so 3.0 only works on browsers that have native module support.

Upgrading an existing project

The Polymer Modulizer tool upgrades Polymer 2.x projects to the npm and ES6 modules format of Polymer 3.0. This tool is in a very early state. There are a number of known issues that should be resolved over the next few weeks. So if you run into problems, don't worry—we're actively working to make it as easy to use as possible.

If you still want to try Modulizer after those disclaimers, see the README for instructions. You can also join the #modulizer channel on Slack if you have questions about Polymer Modulizer.

What now?

Hopefully this post gets you started experimenting with the Polymer 3.0 preview. We'll have more updates over the following days and weeks. Watch this space for an announcement when Polymer Modulizer is ready for wider consumption.