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

Frontend Development Setup

Name: tessl/maven-com-vaadin--vaadin-maven-plugin
Author: tessl

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

Goal Configuration

<goal>prepare-frontend</goal>
<!-- Default phase: process-resources -->
<!-- Dependency resolution: compile-plus-runtime -->

Purpose

This goal performs essential development setup tasks:

Verifies Node.js and npm (or pnpm/bun) installation
Copies frontend resources from JAR dependencies to node_modules
Generates or updates package.json and webpack.config.js files
Propagates build information via system properties and token files
Triggers server redeployment for IDE integration

Configuration Parameters

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

<configuration>
  <!-- Tool verification -->
  <nodeVersion>v18.17.0</nodeVersion>
  <nodeAutoUpdate>true</nodeAutoUpdate>
  <pnpmEnable>true</pnpmEnable>
  <bunEnable>false</bunEnable>
  <useGlobalPnpm>false</useGlobalPnpm>
  <requireHomeNodeExec>false</requireHomeNodeExec>

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

  <!-- Frontend scanning -->
  <frontendScanner>
    <enabled>true</enabled>
    <includeOutputDirectory>true</includeOutputDirectory>
  </frontendScanner>
</configuration>

Usage Examples

Basic Development Setup

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

Custom Node.js Configuration

<plugin>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-maven-plugin</artifactId>
  <version>24.9.0</version>
  <configuration>
    <nodeVersion>v20.9.0</nodeVersion>
    <nodeDownloadRoot>https://nodejs.org/dist/</nodeDownloadRoot>
    <pnpmEnable>true</pnpmEnable>
    <useGlobalPnpm>false</useGlobalPnpm>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>prepare-frontend</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Development with Custom Frontend Directory

<configuration>
  <frontendDirectory>${project.basedir}/client-src</frontendDirectory>
  <npmFolder>${project.basedir}/client-build</npmFolder>
  <generatedTsFolder>${project.basedir}/client-src/generated</generatedTsFolder>
</configuration>

Frontend Scanner Configuration

Control which Maven artifacts are scanned for frontend resources:

<frontendScanner>
  <enabled>true</enabled>
  <includeOutputDirectory>true</includeOutputDirectory>
  <includes>
    <include>
      <groupId>com.vaadin</groupId>
      <artifactId>*</artifactId>
    </include>
    <include>
      <groupId>org.vaadin.addons</groupId>
      <artifactId>my-component</artifactId>
    </include>
  </includes>
  <excludes>
    <exclude>
      <groupId>com.vaadin</groupId>
      <artifactId>flow-server</artifactId>
    </exclude>
  </excludes>
</frontendScanner>

ArtifactMatcher Patterns

<!-- Exact match -->
<groupId>com.vaadin</groupId>
<artifactId>flow-client</artifactId>

<!-- Wildcard patterns -->
<groupId>com.vaadin*</groupId>      <!-- Starts with -->
<artifactId>*-component</artifactId> <!-- Ends with -->
<groupId>*.vaadin.*</groupId>        <!-- Contains -->
<artifactId>*</artifactId>           <!-- All artifacts -->

Generated Files

The goal creates or updates these files:

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

Integration with IDEs

The goal includes IDE integration features:

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

Command Line Execution

# Run prepare-frontend goal
mvn flow:prepare-frontend

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

# Debug execution
mvn flow:prepare-frontend -X

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

Error Handling

Common issues and solutions:

Node.js Not Found

Error: Node.js not found
Solution: Install Node.js or configure nodeDownloadRoot for corporate environments

Permission Issues

Error: Cannot write to directory
Solution: Check file permissions or enable requireHomeNodeExec

Network Issues

Error: Cannot download Node.js
Solution: Configure corporate proxy or use nodeDownloadRoot for internal mirror

Conflicting Lock Files

Warning: Multiple lock files found (package-lock.json and pnpm-lock.yaml)
Solution: Clean frontend and choose one package manager consistently

Install with Tessl CLI

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

docs

code-migration.md

frontend-cleanup.md

frontend-development.md