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>
usingis
orname
. - ⚪️ 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.
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.
DOM APIs
- ✅ Convert to class syntax.
- ✅ Add listeners to ready function.
- ✅ Behaviors as mixins.
- ✅ Automatically import
dom-if.html
anddom-repeat.html
if needed.
Common utility APIs
- ✅ fire - Replaces the
fire
method withdispatchEvent
and adapts the syntax. - ⚪️ async
- ⚪️ debounce
- ⚪️ importHref
- ✅ $$ - Replaces the
$$('selector')
syntax withshadowRoot.querySelector('selector')
.
Additional Features
- Analysis file: Generates a verbose log file showing all the applied changes to each file.
- ...