polymer2-migrator

⚠️ Important: this project is still a WIP and highly experimental.

Migrates a Polymer 1.x component to Polymer 2.x component (class based).

Installation

npm install -g polymer2-migrator

Usage

migrate-component [<folder>|<file>] [--analysis] [--log-level=level]

Examples:

migrate-component
migrate-component ./src
migrate-component file_1.html file_2.html --analysis
migrate-component --log-level=verbose

Options

analysis

If the --analysis flag is used, the migrator will only analyze the component to check which migrations are possible, and generate a migrator-analysis file. It will not make any changes in the component's files.

log-level

Defines the log level of the console output.

Available values: error, warn, info, verbose, debug.

How does it work?

The polymer2-migrator applies the following changes to upgrade your Polymer 1.x component to Polymer 2.x class-based component:

DOM template

• ✅ Remove deprecated patterns in the DOM module: <dom-module> using is or name.
• ⚪ Remove deprecated patterns in the DOM module: styles outside of the template.
• ✅ Update your element's DOM template to use the new <slot> element instead of <content>.
• ⚪ Update any URLs inside the template.

Source

Shadow DOM styles

• ✅ Replace ::content selectors with ::slotted() selectors.
• ✅ Remove /deep/ and ::shadow selectors, if you're still using them.
• ✅ Remove :root selectors.
• ✅ Update custom property syntax.
• ✅ Wrap custom-style elements.

Source

DOM APIs

• ✅ Convert to class syntax.
• ✅ Add listeners to ready function.
• ✅ Behaviors as mixins.
• ✅ Automatically import dom-if.html and dom-repeat.html if needed.

Source

Common utility APIs

• ✅ fire - Replaces the fire method with dispatchEvent and adapts the syntax.
• ⚪ async
• ⚪ debounce
• ⚪ importHref
• ✅ $$ - Replaces the $$('selector') syntax with shadowRoot.querySelector('selector').

Source

Additional Features

• Analysis file: Generates a verbose log file showing all the applied changes to each file.
• ...