0
# Production Build
1

2
The `build-frontend` goal creates optimized frontend bundles for production deployment with comprehensive dependency management and build optimization.
3

4
## Goal Configuration
5

6
```xml { .api }
7
<goal>build-frontend</goal>
8
<!-- Default phase: process-classes -->
9
<!-- Dependency resolution: compile-plus-runtime -->
10
```
11

12
## Purpose
13

14
This goal performs production build tasks:
15
- Updates `package.json` with `@NpmPackage` annotations from classpath
16
- Copies frontend resources from JAR files to `node_modules`
17
- Installs dependencies via npm/pnpm/bun
18
- Updates import files with `@JsModule`, `@Theme`, and `@JavaScript` annotations
19
- Generates optimized webpack bundles
20
- Validates licenses for commercial components
21
- Cleans temporary build files
22

23
## Configuration Parameters
24

25
```xml { .api }
26
<configuration>
27
  <!-- Bundle generation -->
28
  <generateBundle>true</generateBundle>
29
  <optimizeBundle>true</optimizeBundle>
30
  <generateEmbeddableWebComponents>true</generateEmbeddableWebComponents>
31
  <compressBundle>true</compressBundle>
32

33
  <!-- NPM behavior -->
34
  <runNpmInstall>true</runNpmInstall>
35
  <ciBuild>false</ciBuild>
36
  <forceProductionBuild>false</forceProductionBuild>
37

38
  <!-- Directories -->
39
  <frontendResourcesDirectory>${project.basedir}/src/main/resources/META-INF/frontend</frontendResourcesDirectory>
40
  <frontendOutputDirectory>${project.build.outputDirectory}/META-INF/VAADIN/webapp</frontendOutputDirectory>
41

42
  <!-- Cleanup -->
43
  <cleanFrontendFiles>true</cleanFrontendFiles>
44
</configuration>
45
```
46

47
### Boolean Parameters
48

49
```xml { .api }
50
<generateBundle>true|false</generateBundle>                     <!-- Generate frontend bundle -->
51
<runNpmInstall>true|false</runNpmInstall>                      <!-- Run npm install -->
52
<generateEmbeddableWebComponents>true|false</generateEmbeddableWebComponents> <!-- Generate web components -->
53
<optimizeBundle>true|false</optimizeBundle>                    <!-- Use bytecode scanner optimization -->
54
<ciBuild>true|false</ciBuild>                                  <!-- Use npm ci instead of npm install -->
55
<forceProductionBuild>true|false</forceProductionBuild>        <!-- Force build even with default bundle -->
56
<cleanFrontendFiles>true|false</cleanFrontendFiles>            <!-- Clean generated files after build -->
57
```
58

59
### Directory Parameters
60

61
```xml { .api }
62
<frontendResourcesDirectory>path/to/frontend/resources</frontendResourcesDirectory>
63
<frontendOutputDirectory>path/to/output/directory</frontendOutputDirectory>
64
```
65

66
## Usage Examples
67

68
### Basic Production Build
69

70
```xml
71
<plugin>
72
  <groupId>com.vaadin</groupId>
73
  <artifactId>vaadin-maven-plugin</artifactId>
74
  <version>24.9.0</version>
75
  <executions>
76
    <execution>
77
      <goals>
78
        <goal>build-frontend</goal>
79
      </goals>
80
    </execution>
81
  </executions>
82
</plugin>
83
```
84

85
### CI/CD Optimized Build
86

87
```xml
88
<plugin>
89
  <groupId>com.vaadin</groupId>
90
  <artifactId>vaadin-maven-plugin</artifactId>
91
  <version>24.9.0</version>
92
  <configuration>
93
    <ciBuild>true</ciBuild>
94
    <forceProductionBuild>true</forceProductionBuild>
95
    <optimizeBundle>true</optimizeBundle>
96
    <runNpmInstall>true</runNpmInstall>
97
  </configuration>
98
  <executions>
99
    <execution>
100
      <goals>
101
        <goal>build-frontend</goal>
102
      </goals>
103
    </execution>
104
  </executions>
105
</plugin>
106
```
107

108
### Development Build (Faster)
109

110
```xml
111
<configuration>
112
  <generateBundle>false</generateBundle>
113
  <runNpmInstall>false</runNpmInstall>
114
  <optimizeBundle>false</optimizeBundle>
115
  <cleanFrontendFiles>false</cleanFrontendFiles>
116
</configuration>
117
```
118

119
### Custom Resource Directories
120

121
```xml
122
<configuration>
123
  <frontendResourcesDirectory>${project.basedir}/frontend-src</frontendResourcesDirectory>
124
  <frontendOutputDirectory>${project.build.directory}/classes/static</frontendOutputDirectory>
125
</configuration>
126
```
127

128
## Build Process Flow
129

130
1. **Dependency Analysis**: Scans classpath for `@NpmPackage` annotations
131
2. **Resource Copying**: Copies frontend resources from JAR dependencies
132
3. **Package Installation**: Runs npm/pnpm/bun install with resolved dependencies
133
4. **Import Generation**: Updates `generated-flow-imports.js` with discovered modules
134
5. **Webpack Configuration**: Updates `webpack.generated.js` with build settings
135
6. **Bundle Build**: Executes webpack build for production optimization
136
7. **License Validation**: Checks commercial component licenses
137
8. **Cleanup**: Removes temporary files (if cleanFrontendFiles enabled)
138

139
## Bundle Optimization
140

141
### Bytecode Scanner Optimization
142

143
When `optimizeBundle` is enabled, the plugin uses bytecode analysis to discover frontend components:
144

145
```xml { .api }
146
<optimizeBundle>true</optimizeBundle>
147
```
148

149
Benefits:
150
- Faster builds by skipping unnecessary file scanning
151
- More accurate dependency detection
152
- Reduced bundle size through dead code elimination
153

154
### Production Mode Detection
155

156
The plugin automatically detects production mode based on:
157
- Maven profiles
158
- System properties
159
- Execution phase context
160

161
## License Management
162

163
### Commercial Components
164

165
The plugin validates licenses for commercial Vaadin components:
166

167
```xml { .api }
168
<commercialWithBanner>false|true</commercialWithBanner>
169
```
170

171
- `false` (default): Requires valid license for commercial components
172
- `true`: Allows commercial components with banner warning
173

174
### License Validation Process
175

176
1. Scans dependencies for commercial components
177
2. Checks for valid license keys in configuration
178
3. Throws `MissingLicenseKeyException` if license required
179
4. Updates build file with license status
180

181
## React Support
182

183
Automatic React integration when React Router is detected:
184

185
```xml { .api }
186
<reactEnable>true|false|null</reactEnable>
187
```
188

189
- `null` (default): Auto-detect based on routes file
190
- `true`: Force React mode
191
- `false`: Disable React support
192

193
## Hilla Integration
194

195
Special handling for Hilla (full-stack) applications:
196

197
- Automatically detects Hilla usage
198
- Preserves generated frontend files for development
199
- Configures TypeScript generation paths
200

201
## Command Line Execution
202

203
```bash
204
# Standard production build
205
mvn flow:build-frontend
206

207
# Force production build
208
mvn flow:build-frontend -Dvaadin.forceProductionBuild=true
209

210
# CI build with locked dependencies
211
mvn flow:build-frontend -Dvaadin.ciBuild=true
212

213
# Build with custom output directory
214
mvn flow:build-frontend -Dvaadin.frontendOutputDirectory=target/static
215

216
# Debug build process
217
mvn flow:build-frontend -X
218
```
219

220
## Performance Tuning
221

222
### Memory Settings
223

224
For large projects, increase Maven memory:
225

226
```bash
227
export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=512m"
228
mvn flow:build-frontend
229
```
230

231
### Parallel Builds
232

233
Enable parallel dependency resolution:
234

235
```xml
236
<configuration>
237
  <pnpmEnable>true</pnpmEnable>  <!-- pnpm has better parallel performance -->
238
</configuration>
239
```
240

241
### Build Caching
242

243
The plugin includes intelligent caching:
244
- Bundle validation checks if rebuild needed
245
- Dependency change detection
246
- Incremental compilation support
247

248
## Error Handling
249

250
### Build Failures
251

252
```
253
Error: Frontend build failed
254
Solution: Check webpack output, verify Node.js version, ensure dependencies are compatible
255
```
256

257
### Memory Issues
258

259
```
260
Error: JavaScript heap out of memory
261
Solution: Increase Node.js memory limit or Maven heap size
262
```
263

264
### License Errors
265

266
```
267
Error: Missing license key for commercial component
268
Solution: Add license key or enable commercialWithBanner mode
269
```
270

271
### Dependency Conflicts
272

273
```
274
Error: npm ERR! peer dependency conflict
275
Solution: Use ciBuild=false for development, resolve version conflicts in package.json
276
```
277

278
## Integration with Maven Phases
279

280
Typical phase binding:
281

282
```xml
283
<plugin>
284
  <executions>
285
    <execution>
286
      <id>prepare-frontend</id>
287
      <phase>process-resources</phase>
288
      <goals>
289
        <goal>prepare-frontend</goal>
290
      </goals>
291
    </execution>
292
    <execution>
293
      <id>build-frontend</id>
294
      <phase>process-classes</phase>
295
      <goals>
296
        <goal>build-frontend</goal>
297
      </goals>
298
    </execution>
299
  </executions>
300
</plugin>
301
```