0
# Frontend Development Setup
1

2
The `prepare-frontend` goal sets up the development environment for Vaadin Flow applications by verifying tools, managing dependencies, and preparing configuration files.
3

4
## Goal Configuration
5

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

12
## Purpose
13

14
This goal performs essential development setup tasks:
15
- Verifies Node.js and npm (or pnpm/bun) installation
16
- Copies frontend resources from JAR dependencies to `node_modules`
17
- Generates or updates `package.json` and `webpack.config.js` files
18
- Propagates build information via system properties and token files
19
- Triggers server redeployment for IDE integration
20

21
## Configuration Parameters
22

23
All parameters inherit from the base plugin configuration. Key settings:
24

25
```xml { .api }
26
<configuration>
27
  <!-- Tool verification -->
28
  <nodeVersion>v18.17.0</nodeVersion>
29
  <nodeAutoUpdate>true</nodeAutoUpdate>
30
  <pnpmEnable>true</pnpmEnable>
31
  <bunEnable>false</bunEnable>
32
  <useGlobalPnpm>false</useGlobalPnpm>
33
  <requireHomeNodeExec>false</requireHomeNodeExec>
34

35
  <!-- Directory configuration -->
36
  <frontendDirectory>${project.basedir}/src/main/frontend</frontendDirectory>
37
  <npmFolder>${project.basedir}</npmFolder>
38
  <generatedTsFolder>${frontendDirectory}/generated</generatedTsFolder>
39

40
  <!-- Frontend scanning -->
41
  <frontendScanner>
42
    <enabled>true</enabled>
43
    <includeOutputDirectory>true</includeOutputDirectory>
44
  </frontendScanner>
45
</configuration>
46
```
47

48
## Usage Examples
49

50
### Basic Development Setup
51

52
```xml
53
<plugin>
54
  <groupId>com.vaadin</groupId>
55
  <artifactId>vaadin-maven-plugin</artifactId>
56
  <version>24.9.0</version>
57
  <executions>
58
    <execution>
59
      <goals>
60
        <goal>prepare-frontend</goal>
61
      </goals>
62
    </execution>
63
  </executions>
64
</plugin>
65
```
66

67
### Custom Node.js Configuration
68

69
```xml
70
<plugin>
71
  <groupId>com.vaadin</groupId>
72
  <artifactId>vaadin-maven-plugin</artifactId>
73
  <version>24.9.0</version>
74
  <configuration>
75
    <nodeVersion>v20.9.0</nodeVersion>
76
    <nodeDownloadRoot>https://nodejs.org/dist/</nodeDownloadRoot>
77
    <pnpmEnable>true</pnpmEnable>
78
    <useGlobalPnpm>false</useGlobalPnpm>
79
  </configuration>
80
  <executions>
81
    <execution>
82
      <goals>
83
        <goal>prepare-frontend</goal>
84
      </goals>
85
    </execution>
86
  </executions>
87
</plugin>
88
```
89

90
### Development with Custom Frontend Directory
91

92
```xml
93
<configuration>
94
  <frontendDirectory>${project.basedir}/client-src</frontendDirectory>
95
  <npmFolder>${project.basedir}/client-build</npmFolder>
96
  <generatedTsFolder>${project.basedir}/client-src/generated</generatedTsFolder>
97
</configuration>
98
```
99

100
## Frontend Scanner Configuration
101

102
Control which Maven artifacts are scanned for frontend resources:
103

104
```xml { .api }
105
<frontendScanner>
106
  <enabled>true</enabled>
107
  <includeOutputDirectory>true</includeOutputDirectory>
108
  <includes>
109
    <include>
110
      <groupId>com.vaadin</groupId>
111
      <artifactId>*</artifactId>
112
    </include>
113
    <include>
114
      <groupId>org.vaadin.addons</groupId>
115
      <artifactId>my-component</artifactId>
116
    </include>
117
  </includes>
118
  <excludes>
119
    <exclude>
120
      <groupId>com.vaadin</groupId>
121
      <artifactId>flow-server</artifactId>
122
    </exclude>
123
  </excludes>
124
</frontendScanner>
125
```
126

127
### ArtifactMatcher Patterns
128

129
```xml { .api }
130
<!-- Exact match -->
131
<groupId>com.vaadin</groupId>
132
<artifactId>flow-client</artifactId>
133

134
<!-- Wildcard patterns -->
135
<groupId>com.vaadin*</groupId>      <!-- Starts with -->
136
<artifactId>*-component</artifactId> <!-- Ends with -->
137
<groupId>*.vaadin.*</groupId>        <!-- Contains -->
138
<artifactId>*</artifactId>           <!-- All artifacts -->
139
```
140

141
## Generated Files
142

143
The goal creates or updates these files:
144

145
- `package.json` - npm dependencies and scripts
146
- `webpack.config.js` - Webpack configuration for development
147
- `webpack.generated.js` - Generated webpack settings
148
- Token file in output directory - Build information for runtime
149

150
## Integration with IDEs
151

152
The goal includes IDE integration features:
153

154
- **Eclipse/m2eclipse**: Triggers refresh of token file parent directory for hot redeployment
155
- **Build context**: Notifies build system of file changes for incremental compilation
156
- **System properties**: Propagates configuration to runtime environment
157

158
## Command Line Execution
159

160
```bash
161
# Run prepare-frontend goal
162
mvn flow:prepare-frontend
163

164
# Run with specific configuration
165
mvn flow:prepare-frontend -Dvaadin.pnpmEnable=true
166

167
# Debug execution
168
mvn flow:prepare-frontend -X
169

170
# Skip if already prepared (via Maven properties)
171
mvn flow:prepare-frontend -Dvaadin.prepare.skip=true
172
```
173

174
## Error Handling
175

176
Common issues and solutions:
177

178
### Node.js Not Found
179
```
180
Error: Node.js not found
181
Solution: Install Node.js or configure nodeDownloadRoot for corporate environments
182
```
183

184
### Permission Issues
185
```
186
Error: Cannot write to directory
187
Solution: Check file permissions or enable requireHomeNodeExec
188
```
189

190
### Network Issues
191
```
192
Error: Cannot download Node.js
193
Solution: Configure corporate proxy or use nodeDownloadRoot for internal mirror
194
```
195

196
### Conflicting Lock Files
197
```
198
Warning: Multiple lock files found (package-lock.json and pnpm-lock.yaml)
199
Solution: Clean frontend and choose one package manager consistently
200
```