Polymer v1 to v2 Upgrade Cheatsheet with associated lint rules

polymer-upgrade-cheatsheet.md

Upgrade Cheatsheet

This is a simplified version of https://www.polymer-project.org/2.0/docs/upgrade. It also lists what warnings and fixes are available for each upgrade task.

Shadow DOM template and styling

DOM Template

• <dom-module> using is or name should be replaced to use id
  • Warns
  • Fixable: Except dom-modules that contain both name and is
• Move <style> tags inside the <template>
  • Warns
  • Fixable
• Update your element's DOM template to use the new <slot> element instead of <content>
  • Warns
  • Fixable: Except advanced usages including stamping templates
• Update any URLs inside the template.
  • Future: Potentially warn/fix missing importPath and rootPath

Shadow DOM Styles

• Update styles to use the ::slotted() selector in place of ::content
  • Warns
  • Fixable: Except deeper than first descendant
  • Future: Potentially warn on selectors after ::slotted() #169
• Remove any /deep/ and ::shadow CSS rules
  • Warns
• Remove :root selectors #168
  • Warns
  • Fixable
• Update custom property syntax
  • Warns
  • Fixable
• Wrap custom-style elements #166
  • Warns
  • Fixable

DOM APIs

Hybrid Elements

• Polymer.dom returns NodeList now instead of Array

Class-based elements

• Don't use Polymer.dom
• Use this.shadowRoot in place of Polymer.dom(this.root)
  • Future: Potentially, convert usage
• For events, use the standard v1 event API
  • Warns
  • Future: Potentially, fixable
• The Polymer.FlattenedNodesObserver class can be used to replace the 1.x observeNodes method
• Replace the getEffectiveChildren method, use the getFlattenedNodes helper method, and filter down to just the elements
• Replace the getContentChildren method, write platform code to perform this functionality (get the assignedNodes, and filter down to just the elements)

CSS custom property shim

Class-based elements

• The customStyle instance property has been removed. Use updateStyles instead.

Custom elements APIs

Callback contracts have changed

• Lifecycle hooks have changed

Remove type-extension elements

• Remove any type extensions is="" for P2 usages, leave for hybrid

Removed APIs

All could potentially have warnings and potential fixes

• Polymer.instanceof and Polymer.isInstance: no longer needed, use instanceof and instanceof Polymer.Element instead.
• element.getPropertyInfo: This API returned unexpected information some of the time and was rarely used.
• element.getNativePrototype: Removed because it is no longer needed for internal code and was unused by users.
• element.beforeRegister: This was originally added for metadata compatibility with ES6 classes. We now prefer users create ES6 classes by extending Polymer.Element, specifying metadata in the static properties and observers properties.
• element.attributeFollows: Removed due to disuse.
• element.classFollows: Removed due to disuse.
• listeners Removed ability to use id.event to add listeners to elements in shadow DOM. Use declarative template event handlers instead.

Common utility APIs

All could potentially have warnings and potential fixes

• async: this.async(someMethod); or Polymer.Async.microTask.run(() => this.someMethod()); => setTimeout(() => this.someMethod(), 500);
• debounce: this.debounce => Polymer.Debounce.debouncer
• fire: this.fire('some-event') => this.dispatchEvent(new CustomEvent('some-event', { bubbles: true, composed: true }));
• importHref: this.importHref => Polymer.importHref
• $$: $$ => this.shadowRoot.querySelector

Notes

There are other changes that should happen that were hard to represent in a concise list. These changes above should cover the majority of the changes to migrate to using P2.