ember-cli-polymer-bundler

Information

Be cool and use Polymer and Ember together! This addon integrates Polymer with Ember, so you can use the power of custom web components in your ember apps today.

Polymer 2.0

This addon has been updated to for Polymer 2.0! Still want 1.0? Check out the 1.x branch.

Why

Why use Polymer? You might ask. By using Polymer you actually choose to embrace the native Web Components specification, not necessarily Polymer itself. Polymer is only just a thin layer over the Custom Elements v1 specification, providing some syntactic sugar as well as compatibility. Every framework will eventually end up implementing this specification somehow, simply because using native is faster.

Polymer enables you to use any element on webcomponents.org, opening up the world to lots of other good quality components besides the ones on emberaddons.com.

Installation

ember install ember-cli-polymer-bundler

Usage

To use a custom element, just install it through bower.

bower install PolymerElements/paper-button --save

Done! ember-cli-polymer-bundler identifies this package as a custom element and imports it automatically! ✨ You can now use the element:

<paper-button raised>Raised button</paper-button>

Demo

https://dunnkers.github.io/ember-polymer/

Data binding

Polymer's elements should just work with one-way bindings:

<paper-button raised={{raised}}>Raised button</paper-button>

However, for two-way bindings we will need to encapsulate the elements in an Ember Component. Exactly this is what the ember-polymer-paper addon is for!

Requirements

This addon forces Polymer to use Shadow DOM. Browsers that do not natively support Shadow DOM will be supplied with the polyfill. Note that this polyfill might result in slightly slower rendering.

Configuration

Manual imports

If an element is not automatically imported, it probably does not follow the polymer naming conventions. To import it, create elements.html in /app and import the element:

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

Config variables

The addon can be configured in ember-cli-build.js as such:

'ember-cli-polymer-bundler': {
  option: 'value'
}

autoElementImport

Indicates whether elements should be imported automatically. ember-cli-polymer-bundler automatically imports elements from bower packages which have the web-components keyword or a valid html import entry point. All elements at customelements.io should be compatible.

Disable if you want full control over imports yourself. Defaults to true.

  autoElementImport: true

excludeElements

A list with names of bower packages to exclude during auto element import. Comes in handy when you only want to manually import one specific file from a package, but not the entire element.

Defaults to [].

  excludeElements: ['paper-styles']

htmlImportsFile

File to put html imports in. If you do not have manual imports and are using autoElementImport, the file is not necessary.

Defaults to app/elements.html.

  htmlImportsFile: 'app/elements.html'

elementPaths

List of paths that contains in-app Web Components. The HTML bundle is only generated when components inside bower packages or the directories specified as elementPaths change.

Defaults to [].

  elementPaths: [
    'lib/some-folder/web-components'
  ]

bundlerOptions

Allows you to set options used in polymer-bundler.

Defaults to:

  bundlerOptions: {
    stripComments: true
  }

autoprefixer

Allows to apply autoprefixer to the styles found in the bundled html.

Set autoprefixer.enabled to true to activate this feature.

Example:

  autoprefixer: {
    browsers: ['last 2 versions'],
    enabled: true,
    cascade: false
  }

If browsers are not set, the application build targets are used.

bundlerOutput

The output file produced by polymer-bundler for all bundled html code and styling.

Defaults to assets/bundled.html.

  bundlerOutput: 'assets/bundled.html'

polyfillBundle

The polyfill bundle to use. Can be one of hi, hi-ce, hi-sd-ce, sd-ce, lite, loader or none for no polyfills. See the webcomponentsjs how-to-use page.

Defaults to lite.

  polyfillBundle: 'lite'

globalPolymerSettings

Allows you to set global Polymer Settings as described in the Global Polymer settings article.

Defaults to ``.

  globalPolymerSettings: {
    rootPath: '/your/application/root'
  }

lazyImport

Allows to set the rel attribute of the bundle import tag to "lazy-import" instead of "import" to prevent downloading the bundle.

Defaults to false

  lazyImport: true

buildForProduction

Builds the bundled file using polymer build.

The build property accepts an object with the same options for a build using polymer build.

Default configuration:

buildForProduction = {
  enabled: false,
  build: {
    csp: true, // splits HTML and JavaScript for CSP
    js: {
      minify: true,
      compile: true
    },
    css: {
      minify: true
    },
    html: {
      minify: true
    }
  }
};

About

This addon was sponsored by Fabriquartz, a startup based in The Netherlands.