Polymerize for Meteor

Synthesises Polymer and Meteor.

The purpose of this package is to make it incredibly easy to use Polymer in a Meteor project, as if Polymer was made for Meteor. All best practices of integrating Polymer with Meteor should be included as default and require no user action, however the user should be able to override any options easily as well.

Warning

Not production ready. This project is still in prototyping phase. Any API may be subject to change.

Features

As of version 0.4.1, Polymerize supports the following features:

• Add elements using bower install --save
• Automatically imports elements based on the main entry of the bower.json
• Vulcanizing imports when doing a production build or when the environmental variable VULCANIZE is set to true.
• Blaze Compatability. Works with iron:router.
• Defers Blaze.Render until after WebComponentsReady so that Polymer icons load correctly.
• Uses ShadowDOM rather than ShadyDOM for compatability with Blaze
• Temporary workaround for iron-forms issue

Installation

You can add Polymerize to your project via:

meteor add loneleeandroo:polymerize

Run the app once to generate a bower.json and a .bowerrc for your project.

meteor

Ensure that there is a bower.json and a .bowerrc in your project root directory before adding in elements.

Comments

bower.json

If a bower.json file does not exist in your project root directory, this default bower.json will be created:

{
  "name": "my-app",
  "private": true,
  "dependencies": {
    "webcomponentsjs": "^0.7.2",
    "polymer": "Polymer/polymer#^1.0.0"
  }
}

.bowerrc

If a .bowerrc file does not exist in your project root directory, this default .bowerrc will be created:

{
  "directory": "public/bower_components"
}

If you already have a .bowerrc, you will need to change the directory to public/bower_components. This is because the polymer elements requires other files besides the main html import to be available to the client. Currently, placing in the public folder is the most convenient location because it makes files available to the client when building for development and production environments. However, it may cause longer reload times.

Usage

Adding Elements

From bower

You can add any elements to your project via the bower install --save command. For example:

bower install --save PolymerElements/paper-button#^1.0.0

You can browse the catalog of elements to find the commands for adding the elements you want.

The element will be imported into your project automatically. There is no need to manually add a link import to the head of the document. Polymerize will look at the main entry of the bower.jsonin the bower component's folder to figure out which HTML file to import. If you need to manually specify which HTML file to import please use the override entry of the bower.json in the root of your project directory. See comments below on how to create an override entry. The override entry accepts an array, and will load in the order of the array.

From file

TODO

Creating Custom Elements

TODO

Comments

Load Order

Elements are imported in the order which they appear in the bower.json dependencies. It is preferrable to leave webcomponentjs and polymer as the first components to load.

Overriding main file

Unfortunately, there is inconsistency with the main entry in many of the polymer element's bower.json. Some are expressed as arrays, some are strings and some are null. Luckily, Polymerize handles loading the correct main file. However, if you want more control over the process, you are able to override the main entry in the bower.json. For example:

{
  "name": "my-app",
  "private": true,
  "dependencies": {
    "webcomponentsjs": "^0.7.2",
    "polymer": "Polymer/polymer#^1.0.0"
  },
  "overrides": {
    "polymer": {
      "main": [
        "polymer-micro.html"
      ]
    }
  }
}

Vulcanize

Polymer elements are automatically vulcanized when building or running your meteor app as production. Polymerize will look at process.env.NODE_ENV. If you want want to vulcanize your elements in development, you can pass the environment variable VULCANIZE before your meteor commands. For example:

VULCANIZE=true meteor

ShadowDOM polyfill

For compatability with Blaze, it is essential to use the ShadowDOM rather than ShadyDOM to write to the local DOM. Browsers such as Chrome, already have native ShadowDOM support and will render perfectly. On the other hand, browsers such as Safari and Firefox will require the ShadowDOM polyfill, which is not included in webcomponentsjs-lite.js, so you'll need to use the full version instead, which is webcomponentsjs.js.

Roadmap

• Write TinyTests for the package.
• Implement an easy workflow for creating custom elements and using the Polymer API.
• Look at ways to implement Server Side Rendering for Polymer elements.