> Markdown version of [Migration Tool for Polymer Templates](https://vaadin.com/docs/v14/flow/upgrading/v10-13/migration-tool). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# Migration Tool for Polymer Templates

> **Caution:** The Polymer 2 to Polymer 3 migration tool is not actively maintained and it has issues. You can try if it works in your project, but we are not going to spend time on fixing issue in it unless those are prioritized as part of Warranty.

> **Note:** There are currently some issues in running the migration tool on Windows. The error output refers to "bower install failing" or "git not being available on path". As a workaround, use the [Windows Linux Subsystem](https://docs.microsoft.com/en-us/windows/wsl/install-win10) and run the tool there instead.

Several steps are required to migrate your project to Vaadin 14 from Vaadin 13, see [Vaadin 14 Migration Guide](https://vaadin.com/docs/v14/flow/upgrading/v10-13.md) tutorial. To help with the migration, the Vaadin 14 migration tool can update Polymer 2 HTML templates in an existing Vaadin 13 project into Polymer 3 JavaScript modules.

The Vaadin 14 migration tool is available in two forms: as a goal in `vaadin-maven-plugin` (for Maven-based projects), and as a standalone jar (for other project setups)

## <a id="migrating-a-maven-project"></a>Migrating a Maven Project

The plugin’s `migrate-to-p3` goal automates two steps:

- it uses resources directory (by default it is `src/main/webapp`) to locate Polymer 2 templates HTML files, converts them into Polymer 3 format and moves them into `frontend` folder inside your project root directory.

- it finds all Java class declarations annotated with `@HtmlImport` and `@StyleSheet` in the project source files and rewrites annotation to `@JsModule` annotation along with path (`value` parameter) update.

This goal can be executed from command line with

```
mvn vaadin:migrate-to-p3
```

or with most IDEs from a list of configured Maven plugin goals for a project. The template migration tool is also available as a [Java executable](#standalone) for non-Maven projects.

> **Note:** The migration tool takes care about style files and `@StyleSheet` annotations converting them into `@JsModule`. But there is `@CssImport` annotation available which is more convenient to use instead of `@JsModule` for CSS. The migration tool is not able to convert styles using `@CssImport` annotation. This requires manual conversation.

The migration tool doesn’t preserve HTML comments from your original template files. Important HTML comments should therefore be manually transferred to the converted P3 files. To facilitate this, use the **keepOriginal** parameter to prevent removal of the original template files (by default these are removed). See **keepOriginal** parameter description below.

### <a id="goal-parameters"></a>Goal parameters

Here we describe the Maven plugin goal’s parameters. These can be configured in the `<configuration>` section inside the `vaadin-maven-plugin`'s `<plugin>` tag.

- **resources** (default: `${project.basedir}/src/main/webapp`): List of folder paths that should be used to locate the P2 resources to convert them into P3 modules. It’s configured in the pom file via `<resources>` parent element and `<resource>` child elements inside it.

- **migrateFolder** (default: `${project.build.directory}/migration`): A temporary directory which is used internally to store copies of the resource files and their conversation to P3. The result files will be moved to the final destination from it.

- **frontendDirectory** (default: `${project.basedir}/frontend`): The resulting directory which will contain converted resource files.

- **keepOriginal** (default: `false`): Whether to keep original resource files or not. By default the converted resource files will be removed.

- **ignoreModulizerErrors** (default: `true`): Whether the Maven build should fail if modulizer internal tool returns non zero exit status. Even if Modulizer exists with error it doesn’t mean that conversation wasn’t done. So by default the Maven build won’t fail even though there were errors.

- **annotationsRewrite** (default: `ALWAYS`): Defines a strategy to rewrite `@HtmlImport`/`@StyleSheet` annotations in Java source files. There are three values available:

  - `ALWAY` means rewrite annotations regardless of resource conversation status

  - `SKIP` means skip annotations rewrite

  - `SKIP_ON_ERROR` means rewrite only if there are no errors during resource conversation

## <a id="standalone"></a>Migrating a Project Using the Standalone Tool

The standalone migration tool can be used to migrate projects that do not use Maven. It performs the same tasks as the Maven plugin, but requires more parameters since fewer assumptions can be made about the project structure.

The standalone migration tool is distributed as a separate `.jar` file, which can be downloaded from Maven central: <https://repo.maven.apache.org/maven2/com/vaadin/flow-migration/>

You should download the jar file named `flow-migration-<VERSION>-standalone.jar`, where `<VERSION>` is synchronized with Flow release versions. We recommend to to always download the latest version of the migration tool.

You can run the jar on the command line (`java -jar flow-migration-<VERSION>-standalone.jar` followed by the list of parameters and values). The tool requires the following mandatory parameters (path values are absolute, or resolved relative to current working directory if not starting with `/`) unless explicitly specified to be relative to `baseDir`:

- `-b,--baseDir <arg>`: Base project directory. Normally it is the root of the files to migrate.

- `-c,--classesDir <arg>`: Compiled classes directory. Java classes have to be compiled into this directory to be able to apply migration.

- `-d,--depUrls <arg>`: Comma-separated classpath URLs. The URLs should include all dependencies for the project such as jars or filesystem paths to binary classes.

- `-src,--sourceDirs <arg>`: Comma-separated java source directories. The root package directory (e.g. `com`) should exist in this directory.

In addition, the tool supports the following optional parameters:

- `-ars,--annRewrite <arg>`: Java annotation rewrite strategy (see above for details). Legal values are `ALWAYS`, `SKIP_ON_ERROR` and `SKIP`.

- `-ko,--keepOriginal`: See description of **keepOriginal** above.

- `-md,--migrationDir <arg>`: See description of **migrateFolder** above.

- `-res,--resourcesDirs <arg>`: See description of **resources** above.

- `-se,--stopOnError`: Whether migration should stop execution with error if Modulizer has exited with non-zero status.

- `-t,--targetDir <arg>`: See description of **frontendDirectory** above.

### <a id="example"></a>Example

To convert a project in directory `/tmp/myproject`, containing Java sources in `/tmp/myproject/src/main/java` and compiled Java classes in `/tmp/myproject/target/classes` with default options:

```
java -jar flow-migration-<VERSION>-standalone.jar \
  -b /tmp/myproject
  -src /tmp/myproject/src/main/java
  -c /tmp/myproject/target/classes
  -d file:///tmp/flow-server-2.0.8.jar
```

Note that `flow-server` is a minimal dependency required for `-d` (as the standalone migration tool is agnostic of the project setup, it needs to be instructed where to find the classes that the project depends on, including the Vaadin classes).

`20E49937-2744-423C-96EA-DE12ECB93A50`
