CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-vaadin--vaadin-maven-plugin

Maven plugin for Vaadin Flow applications that handles frontend resource management, webpack bundling, and development workflow automation

Overview
Eval results
Files

code-migration.mddocs/

Code Migration

The convert-polymer goal automates migration from legacy Polymer-based components to modern Lit framework, improving performance and maintainability.

Goal Configuration

<goal>convert-polymer</goal>
<!-- No default phase - must be explicitly executed -->

Purpose

This goal performs automated code migration:

  • Converts Polymer template syntax to Lit
  • Updates JavaScript/TypeScript imports and exports
  • Transforms property definitions and decorators
  • Modernizes event handling patterns
  • Updates lifecycle method calls

Configuration Parameters

<configuration>
  <!-- Target conversion path -->
  <path>path/to/specific/file/or/directory</path>

  <!-- Lit version compatibility -->
  <useLit1>false</useLit1>

  <!-- JavaScript compatibility -->
  <disableOptionalChaining>false</disableOptionalChaining>
</configuration>

Parameter Details

<path>string</path>                                    <!-- Specific file or directory to convert -->
<useLit1>true|false</useLit1>                         <!-- Enforce Lit 1.x compatible imports -->
<disableOptionalChaining>true|false</disableOptionalChaining> <!-- Disable ?. operator usage -->

Usage Examples

Basic Conversion

<plugin>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-maven-plugin</artifactId>
  <version>24.9.0</version>
  <executions>
    <execution>
      <goals>
        <goal>convert-polymer</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Convert Specific Directory

<plugin>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-maven-plugin</artifactId>
  <version>24.9.0</version>
  <configuration>
    <path>src/main/frontend/components</path>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>convert-polymer</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Lit 1.x Compatibility

<configuration>
  <useLit1>true</useLit1>
  <disableOptionalChaining>true</disableOptionalChaining>
</configuration>

Convert Single File

<configuration>
  <path>src/main/frontend/views/my-polymer-view.js</path>
</configuration>

Conversion Process

Default Scanning

When no path is specified, the goal scans and converts:

  • All *.js files in the project
  • All *.java files with Polymer template strings
  • Excludes node_modules directory automatically

File Types Processed

// JavaScript/TypeScript files
my-component.js
my-component.ts

// Java files with embedded templates
@Tag("my-component")
@JsModule("./my-component.js")
public class MyComponent extends LitTemplate {
    // Polymer template strings in Java
}

Conversion Transformations

Import Statements

Before (Polymer):

import { PolymerElement, html } from '@polymer/polymer';
import '@polymer/paper-button/paper-button.js';

After (Lit):

import { LitElement, html, css } from 'lit';
import '@material/mwc-button/mwc-button.js';

Class Definitions

Before (Polymer):

class MyElement extends PolymerElement {
  static get template() {
    return html`<div>[[title]]</div>`;
  }

  static get properties() {
    return {
      title: String
    };
  }
}

After (Lit):

class MyElement extends LitElement {
  static properties = {
    title: { type: String }
  };

  render() {
    return html`<div>${this.title}</div>`;
  }
}

Property Binding Syntax

Before (Polymer):

html`
  <div>[[property]]</div>
  <input value="{{userInput::input}}">
  <button on-click="handleClick">Click</button>
`

After (Lit):

html`
  <div>${this.property}</div>
  <input .value="${this.userInput}" @input="${this.handleInput}">
  <button @click="${this.handleClick}">Click</button>
`

Command Line Execution

# Convert entire project
mvn flow:convert-polymer

# Convert specific directory
mvn flow:convert-polymer -Dvaadin.path=src/main/frontend/views

# Convert with Lit 1 compatibility
mvn flow:convert-polymer -Dvaadin.useLit1=true

# Convert without optional chaining
mvn flow:convert-polymer -Dvaadin.disableOptionalChaining=true

# Convert specific file
mvn flow:convert-polymer -Dvaadin.path=src/main/frontend/my-view.js

Hilla Project Warning

The conversion tool is not intended for Hilla projects since Polymer templates are not supported in Hilla. When executed in a Hilla project, the goal will display a warning:

The 'convert-polymer' goal is not meant to be used in Hilla projects as polymer templates are not supported.

Advanced Conversion Options

Lit 1.x Compatibility Mode

When useLit1 is enabled:

  • Uses Lit 1.x import paths
  • Generates Lit 1.x compatible property syntax
  • Maintains backward compatibility with older Lit versions

Optional Chaining Compatibility

When disableOptionalChaining is enabled:

  • Avoids using the ?. operator
  • Improves compatibility with older JavaScript environments
  • Uses traditional null/undefined checks

Pre-Conversion Checklist

Before running the conversion:

  1. Backup your code - The conversion modifies files in place
  2. Review Polymer usage - Understand current Polymer patterns
  3. Check dependencies - Ensure Lit dependencies are available
  4. Test environment - Verify Node.js and build tools are working

Post-Conversion Steps

After conversion completion:

  1. Review generated code - Check for any conversion issues
  2. Update package.json - Add Lit dependencies, remove Polymer
  3. Run tests - Verify functionality after conversion
  4. Update build configuration - Adjust webpack/bundler settings
  5. Update documentation - Reflect new Lit patterns

Manual Review Required

The automated conversion handles most cases but may require manual review for:

Complex Event Handling

// May need manual adjustment
handleComplexEvent(e) {
  // Custom Polymer patterns might not convert perfectly
}

Custom Property Observers

// Polymer observers need manual conversion to Lit reactive properties
static get observers() {
  return ['_titleChanged(title)'];  // Needs manual Lit lifecycle conversion
}

Advanced Data Binding

// Complex data binding expressions may need review
html`<div>[[_computeValue(prop1, prop2)]]</div>`  // Check Lit equivalent

Error Handling

Conversion Failures

Error: Cannot convert file
Solution: Check file syntax, ensure valid JavaScript/TypeScript, try converting smaller sections

Unsupported Patterns

Warning: Pattern not converted automatically
Solution: Review generated code, apply manual conversion for complex patterns

File Permission Issues

Error: Cannot write converted file
Solution: Check file permissions, ensure files are not read-only

Integration with Development Workflow

Gradual Migration

# Convert one component at a time
mvn flow:convert-polymer -Dvaadin.path=src/main/frontend/components/user-card.js
mvn compile  # Test compilation
mvn test     # Run tests

# Continue with next component
mvn flow:convert-polymer -Dvaadin.path=src/main/frontend/components/nav-bar.js

Batch Processing

<!-- Maven profile for batch conversion -->
<profile>
  <id>convert-to-lit</id>
  <build>
    <plugins>
      <plugin>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>convert-components</id>
            <goals>
              <goal>convert-polymer</goal>
            </goals>
            <configuration>
              <path>src/main/frontend/components</path>
            </configuration>
          </execution>
          <execution>
            <id>convert-views</id>
            <goals>
              <goal>convert-polymer</goal>
            </goals>
            <configuration>
              <path>src/main/frontend/views</path>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

Activate with:

mvn compile -Pconvert-to-lit

Install with Tessl CLI

npx tessl i tessl/maven-com-vaadin--vaadin-maven-plugin

docs

code-migration.md

frontend-cleanup.md

frontend-development.md

index.md

production-build.md

sbom-generation.md

tile.json