0
# Vaadin Maven Plugin
1

2
The Vaadin Maven Plugin is a comprehensive build tool for Vaadin Flow applications that handles frontend resource management, webpack bundling, and development workflow automation. It provides Maven goals for preparing frontend dependencies, building production bundles, and managing the complete lifecycle of modern web applications built with the Vaadin Flow framework.
3

4
## Package Information
5

6
- **Package Name**: vaadin-maven-plugin
7
- **Group ID**: com.vaadin
8
- **Package Type**: Maven Plugin
9
- **Language**: Java
10
- **Installation**: Add plugin to Maven `pom.xml` (see Basic Usage)
11

12
## Core Configuration
13

14
The plugin is configured in the Maven `pom.xml` build section:
15

16
```xml
17
<build>
18
  <plugins>
19
    <plugin>
20
      <groupId>com.vaadin</groupId>
21
      <artifactId>vaadin-maven-plugin</artifactId>
22
      <version>24.9.0</version>
23
    </plugin>
24
  </plugins>
25
</build>
26
```
27

28
## Basic Usage
29

30
```xml
31
<build>
32
  <plugins>
33
    <plugin>
34
      <groupId>com.vaadin</groupId>
35
      <artifactId>vaadin-maven-plugin</artifactId>
36
      <version>24.9.0</version>
37
      <executions>
38
        <execution>
39
          <goals>
40
            <goal>prepare-frontend</goal>
41
          </goals>
42
        </execution>
43
      </executions>
44
    </plugin>
45
  </plugins>
46
</build>
47
```
48

49
Run goals via Maven:
50
```bash
51
mvn flow:prepare-frontend
52
mvn flow:build-frontend
53
```
54

55
## Capabilities
56

57
### Frontend Development Setup
58

59
Prepares the development environment by verifying Node.js/npm installation and setting up frontend dependencies.
60

61
```xml { .api }
62
<goal>prepare-frontend</goal>
63
```
64

65
The `prepare-frontend` goal verifies requirements, copies frontend resources from JAR dependencies, and generates configuration files.
66

67
[Frontend Development Setup](./frontend-development.md)
68

69
### Production Build
70

71
Builds optimized frontend bundles for production deployment with complete dependency management.
72

73
```xml { .api }
74
<goal>build-frontend</goal>
75
```
76

77
The `build-frontend` goal creates production-ready bundles with npm dependency installation and webpack optimization.
78

79
[Production Build](./production-build.md)
80

81
### Frontend Cleanup
82

83
Cleans frontend files and removes generated artifacts to reset the project to a clean state.
84

85
```xml { .api }
86
<goal>clean-frontend</goal>
87
<!-- Easter egg alias -->
88
<goal>dance</goal>
89
```
90

91
Both goals remove node_modules, lock files, and generated frontend artifacts.
92

93
[Frontend Cleanup](./frontend-cleanup.md)
94

95
### Code Migration
96

97
Converts legacy Polymer-based components to modern Lit framework for improved performance and maintainability.
98

99
```xml { .api }
100
<goal>convert-polymer</goal>
101
```
102

103
Automated conversion tool for migrating Polymer templates to Lit components.
104

105
[Code Migration](./code-migration.md)
106

107
### Software Bill of Materials (SBOM)
108

109
Generates CycloneDX SBOM files for both backend (Maven) and frontend (npm) dependencies for security and compliance.
110

111
```xml { .api }
112
<goal>generate-maven-sbom</goal>
113
<goal>generate-npm-sbom</goal>
114
```
115

116
Creates standardized SBOM files for dependency tracking and vulnerability analysis.
117

118
[SBOM Generation](./sbom-generation.md)
119

120
### Maven SBOM Generation
121

122
Generates CycloneDX SBOM files for backend Java dependencies for security compliance and vulnerability analysis.
123

124
```xml { .api }
125
<goal>generate-maven-sbom</goal>
126
```
127

128
Creates standardized SBOM files for Maven dependency tracking and security analysis.
129

130
### NPM SBOM Generation
131

132
Generates CycloneDX SBOM files for frontend npm dependencies for complete dependency visibility.
133

134
```xml { .api }
135
<goal>generate-npm-sbom</goal>
136
```
137

138
Creates SBOM files for frontend dependency tracking and vulnerability scanning.
139

140
## Common Configuration Parameters
141

142
### Directory Configuration
143

144
```xml { .api }
145
<configuration>
146
  <frontendDirectory>${project.basedir}/src/main/frontend</frontendDirectory>
147
  <npmFolder>${project.basedir}</npmFolder>
148
  <javaSourceFolder>${project.basedir}/src/main/java</javaSourceFolder>
149
  <javaResourceFolder>${project.basedir}/src/main/resources</javaResourceFolder>
150
</configuration>
151
```
152

153
### Node.js Configuration
154

155
```xml { .api }
156
<configuration>
157
  <nodeVersion>v18.17.0</nodeVersion>
158
  <nodeAutoUpdate>true</nodeAutoUpdate>
159
  <nodeDownloadRoot>https://nodejs.org/dist/</nodeDownloadRoot>
160
  <requireHomeNodeExec>false</requireHomeNodeExec>
161
</configuration>
162
```
163

164
### Package Manager Configuration
165

166
```xml { .api }
167
<configuration>
168
  <pnpmEnable>true</pnpmEnable>
169
  <bunEnable>false</bunEnable>
170
  <useGlobalPnpm>false</useGlobalPnpm>
171
  <postinstallPackages>
172
    <param>package-name-1</param>
173
    <param>package-name-2</param>
174
  </postinstallPackages>
175
</configuration>
176
```
177

178
### Production Settings
179

180
```xml { .api }
181
<configuration>
182
  <productionMode>false</productionMode>
183
  <optimizeBundle>true</optimizeBundle>
184
  <generateBundle>true</generateBundle>
185
  <commercialWithBanner>false</commercialWithBanner>
186
  <reactEnable>null</reactEnable>
187
</configuration>
188
```
189

190
### Development Settings
191

192
```xml { .api }
193
<configuration>
194
  <frontendHotdeploy>null</frontendHotdeploy>
195
  <skipDevBundleRebuild>false</skipDevBundleRebuild>
196
  <frontendIgnoreVersionChecks>false</frontendIgnoreVersionChecks>
197
  <npmExcludeWebComponents>false</npmExcludeWebComponents>
198
  <frontendExtraFileExtensions>
199
    <param>extension1</param>
200
    <param>extension2</param>
201
  </frontendExtraFileExtensions>
202
</configuration>
203
```
204

205
### Application Configuration
206

207
```xml { .api }
208
<configuration>
209
  <applicationIdentifier>my-app</applicationIdentifier>
210
  <eagerServerLoad>null</eagerServerLoad>
211
  <generatedTsFolder>${frontendDirectory}/generated</generatedTsFolder>
212
  <openApiJsonFile>${project.build.directory}/generated-resources/openapi.json</openApiJsonFile>
213
</configuration>
214
```
215

216
## Types
217

218
```xml { .api }
219
<!-- Directory path configuration -->
220
<frontendDirectory>path</frontendDirectory>
221
<npmFolder>path</npmFolder>
222
<generatedTsFolder>path</generatedTsFolder>
223
<javaSourceFolder>path</javaSourceFolder>
224
<javaResourceFolder>path</javaResourceFolder>
225
<resourceOutputDirectory>path</resourceOutputDirectory>
226
<frontendOutputDirectory>path</frontendOutputDirectory>
227
<frontendResourcesDirectory>path</frontendResourcesDirectory>
228
<projectBuildDir>path</projectBuildDir>
229

230
<!-- Boolean flags -->
231
<productionMode>true|false|null</productionMode>
232
<generateBundle>true|false</generateBundle>
233
<runNpmInstall>true|false</runNpmInstall>
234
<optimizeBundle>true|false</optimizeBundle>
235
<pnpmEnable>true|false</pnpmEnable>
236
<bunEnable>true|false</bunEnable>
237
<useGlobalPnpm>true|false</useGlobalPnpm>
238
<nodeAutoUpdate>true|false</nodeAutoUpdate>
239
<requireHomeNodeExec>true|false</requireHomeNodeExec>
240
<commercialWithBanner>true|false</commercialWithBanner>
241
<skipDevBundleRebuild>true|false</skipDevBundleRebuild>
242
<frontendIgnoreVersionChecks>true|false</frontendIgnoreVersionChecks>
243
<npmExcludeWebComponents>true|false</npmExcludeWebComponents>
244
<generateEmbeddableWebComponents>true|false</generateEmbeddableWebComponents>
245
<ciBuild>true|false</ciBuild>
246
<forceProductionBuild>true|false</forceProductionBuild>
247
<cleanFrontendFiles>true|false</cleanFrontendFiles>
248

249
<!-- Boolean or null flags -->
250
<reactEnable>true|false|null</reactEnable>
251
<frontendHotdeploy>true|false|null</frontendHotdeploy>
252
<eagerServerLoad>true|false|null</eagerServerLoad>
253

254
<!-- String values -->
255
<nodeVersion>version</nodeVersion>
256
<nodeDownloadRoot>url</nodeDownloadRoot>
257
<applicationIdentifier>identifier</applicationIdentifier>
258

259
<!-- Array values -->
260
<postinstallPackages>
261
  <param>package-name-1</param>
262
  <param>package-name-2</param>
263
</postinstallPackages>
264
<frontendExtraFileExtensions>
265
  <param>extension1</param>
266
  <param>extension2</param>
267
</frontendExtraFileExtensions>
268
```
269

270
## Advanced Configuration
271

272
### Frontend Scanner Configuration
273

274
Control which dependencies are scanned for frontend resources:
275

276
```xml { .api }
277
<frontendScanner>
278
  <enabled>true</enabled>
279
  <includeOutputDirectory>true</includeOutputDirectory>
280
  <includes>
281
    <include>
282
      <groupId>com.vaadin*</groupId>
283
      <artifactId>*</artifactId>
284
    </include>
285
  </includes>
286
  <excludes>
287
    <exclude>
288
      <groupId>com.example</groupId>
289
      <artifactId>unwanted-*</artifactId>
290
    </exclude>
291
  </excludes>
292
</frontendScanner>
293
```
294

295
## Error Handling
296

297
The plugin provides detailed error messages and troubleshooting guidance:
298

299
- **Node.js/npm not found**: Install Node.js or configure `nodeVersion` and `nodeDownloadRoot`
300
- **Permission errors**: Check file system permissions or enable `requireHomeNodeExec`
301
- **Build failures**: Enable debug logging with `mvn -X` for detailed diagnostics
302
- **Version conflicts**: The plugin checks Flow framework compatibility and warns about mismatches
303

304
Common troubleshooting approaches:
305
- Use `mvn flow:clean-frontend` to reset frontend state
306
- Check Maven debug output with `-X` flag
307
- Verify Node.js and npm versions are compatible
308
- Ensure project has proper Maven structure and dependencies