0
# Code Migration
1

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

4
## Goal Configuration
5

6
```xml { .api }
7
<goal>convert-polymer</goal>
8
<!-- No default phase - must be explicitly executed -->
9
```
10

11
## Purpose
12

13
This goal performs automated code migration:
14
- Converts Polymer template syntax to Lit
15
- Updates JavaScript/TypeScript imports and exports
16
- Transforms property definitions and decorators
17
- Modernizes event handling patterns
18
- Updates lifecycle method calls
19

20
## Configuration Parameters
21

22
```xml { .api }
23
<configuration>
24
  <!-- Target conversion path -->
25
  <path>path/to/specific/file/or/directory</path>
26

27
  <!-- Lit version compatibility -->
28
  <useLit1>false</useLit1>
29

30
  <!-- JavaScript compatibility -->
31
  <disableOptionalChaining>false</disableOptionalChaining>
32
</configuration>
33
```
34

35
### Parameter Details
36

37
```xml { .api }
38
<path>string</path>                                    <!-- Specific file or directory to convert -->
39
<useLit1>true|false</useLit1>                         <!-- Enforce Lit 1.x compatible imports -->
40
<disableOptionalChaining>true|false</disableOptionalChaining> <!-- Disable ?. operator usage -->
41
```
42

43
## Usage Examples
44

45
### Basic Conversion
46

47
```xml
48
<plugin>
49
  <groupId>com.vaadin</groupId>
50
  <artifactId>vaadin-maven-plugin</artifactId>
51
  <version>24.9.0</version>
52
  <executions>
53
    <execution>
54
      <goals>
55
        <goal>convert-polymer</goal>
56
      </goals>
57
    </execution>
58
  </executions>
59
</plugin>
60
```
61

62
### Convert Specific Directory
63

64
```xml
65
<plugin>
66
  <groupId>com.vaadin</groupId>
67
  <artifactId>vaadin-maven-plugin</artifactId>
68
  <version>24.9.0</version>
69
  <configuration>
70
    <path>src/main/frontend/components</path>
71
  </configuration>
72
  <executions>
73
    <execution>
74
      <goals>
75
        <goal>convert-polymer</goal>
76
      </goals>
77
    </execution>
78
  </executions>
79
</plugin>
80
```
81

82
### Lit 1.x Compatibility
83

84
```xml
85
<configuration>
86
  <useLit1>true</useLit1>
87
  <disableOptionalChaining>true</disableOptionalChaining>
88
</configuration>
89
```
90

91
### Convert Single File
92

93
```xml
94
<configuration>
95
  <path>src/main/frontend/views/my-polymer-view.js</path>
96
</configuration>
97
```
98

99
## Conversion Process
100

101
### Default Scanning
102

103
When no `path` is specified, the goal scans and converts:
104
- All `*.js` files in the project
105
- All `*.java` files with Polymer template strings
106
- Excludes `node_modules` directory automatically
107

108
### File Types Processed
109

110
```javascript
111
// JavaScript/TypeScript files
112
my-component.js
113
my-component.ts
114

115
// Java files with embedded templates
116
@Tag("my-component")
117
@JsModule("./my-component.js")
118
public class MyComponent extends LitTemplate {
119
    // Polymer template strings in Java
120
}
121
```
122

123
## Conversion Transformations
124

125
### Import Statements
126

127
**Before (Polymer):**
128
```javascript
129
import { PolymerElement, html } from '@polymer/polymer';
130
import '@polymer/paper-button/paper-button.js';
131
```
132

133
**After (Lit):**
134
```javascript
135
import { LitElement, html, css } from 'lit';
136
import '@material/mwc-button/mwc-button.js';
137
```
138

139
### Class Definitions
140

141
**Before (Polymer):**
142
```javascript
143
class MyElement extends PolymerElement {
144
  static get template() {
145
    return html`<div>[[title]]</div>`;
146
  }
147

148
  static get properties() {
149
    return {
150
      title: String
151
    };
152
  }
153
}
154
```
155

156
**After (Lit):**
157
```javascript
158
class MyElement extends LitElement {
159
  static properties = {
160
    title: { type: String }
161
  };
162

163
  render() {
164
    return html`<div>${this.title}</div>`;
165
  }
166
}
167
```
168

169
### Property Binding Syntax
170

171
**Before (Polymer):**
172
```javascript
173
html`
174
  <div>[[property]]</div>
175
  <input value="{{userInput::input}}">
176
  <button on-click="handleClick">Click</button>
177
`
178
```
179

180
**After (Lit):**
181
```javascript
182
html`
183
  <div>${this.property}</div>
184
  <input .value="${this.userInput}" @input="${this.handleInput}">
185
  <button @click="${this.handleClick}">Click</button>
186
`
187
```
188

189
## Command Line Execution
190

191
```bash
192
# Convert entire project
193
mvn flow:convert-polymer
194

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

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

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

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

208
## Hilla Project Warning
209

210
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:
211

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

216
## Advanced Conversion Options
217

218
### Lit 1.x Compatibility Mode
219

220
When `useLit1` is enabled:
221
- Uses Lit 1.x import paths
222
- Generates Lit 1.x compatible property syntax
223
- Maintains backward compatibility with older Lit versions
224

225
### Optional Chaining Compatibility
226

227
When `disableOptionalChaining` is enabled:
228
- Avoids using the `?.` operator
229
- Improves compatibility with older JavaScript environments
230
- Uses traditional null/undefined checks
231

232
## Pre-Conversion Checklist
233

234
Before running the conversion:
235

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

241
## Post-Conversion Steps
242

243
After conversion completion:
244

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

251
## Manual Review Required
252

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

255
### Complex Event Handling
256

257
```javascript
258
// May need manual adjustment
259
handleComplexEvent(e) {
260
  // Custom Polymer patterns might not convert perfectly
261
}
262
```
263

264
### Custom Property Observers
265

266
```javascript
267
// Polymer observers need manual conversion to Lit reactive properties
268
static get observers() {
269
  return ['_titleChanged(title)'];  // Needs manual Lit lifecycle conversion
270
}
271
```
272

273
### Advanced Data Binding
274

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

280
## Error Handling
281

282
### Conversion Failures
283

284
```
285
Error: Cannot convert file
286
Solution: Check file syntax, ensure valid JavaScript/TypeScript, try converting smaller sections
287
```
288

289
### Unsupported Patterns
290

291
```
292
Warning: Pattern not converted automatically
293
Solution: Review generated code, apply manual conversion for complex patterns
294
```
295

296
### File Permission Issues
297

298
```
299
Error: Cannot write converted file
300
Solution: Check file permissions, ensure files are not read-only
301
```
302

303
## Integration with Development Workflow
304

305
### Gradual Migration
306

307
```bash
308
# Convert one component at a time
309
mvn flow:convert-polymer -Dvaadin.path=src/main/frontend/components/user-card.js
310
mvn compile  # Test compilation
311
mvn test     # Run tests
312

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

317
### Batch Processing
318

319
```xml
320
<!-- Maven profile for batch conversion -->
321
<profile>
322
  <id>convert-to-lit</id>
323
  <build>
324
    <plugins>
325
      <plugin>
326
        <groupId>com.vaadin</groupId>
327
        <artifactId>vaadin-maven-plugin</artifactId>
328
        <executions>
329
          <execution>
330
            <id>convert-components</id>
331
            <goals>
332
              <goal>convert-polymer</goal>
333
            </goals>
334
            <configuration>
335
              <path>src/main/frontend/components</path>
336
            </configuration>
337
          </execution>
338
          <execution>
339
            <id>convert-views</id>
340
            <goals>
341
              <goal>convert-polymer</goal>
342
            </goals>
343
            <configuration>
344
              <path>src/main/frontend/views</path>
345
            </configuration>
346
          </execution>
347
        </executions>
348
      </plugin>
349
    </plugins>
350
  </build>
351
</profile>
352
```
353

354
Activate with:
355
```bash
356
mvn compile -Pconvert-to-lit
357
```