Docs

Docs

Production Build

How to create a production-ready package of an application, which can then be deployed.

If you generated your application with Hilla CLI, you can create a production build by running the following command on the command-line:

Source code
terminal
mvn clean package

Executing this line builds a JAR file with all of the dependencies and bundled frontend resources, ready to be deployed. You can find the file in the target folder after the build is finished.

Enabling Production Builds

The production build command works out-of-the-box for Hilla starter projects. For example, it works with projects that are generated using the Hilla CLI. The starter projects come with the necessary Maven configuration. If you’ve manually created your project’s pom.xml file, add the following vaadin-maven-plugin to enable production builds:

Source code
pom.xml
<build>
    <plugins>
        <plugin>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-maven-plugin</artifactId>
            <version>${vaadin.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>build-frontend</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

The exact plugin configuration may vary depending on your environment, but all variants use the vaadin:build-frontend goal.

Creating a Production Build

To create a production build, you can execute mvn clean package. This builds a JAR or WAR file with all of the dependencies and frontend resources compiled and ready to be deployed. The file is created in the target folder after the build completes.

If you don’t have the build-frontend goal in your POM file, the easiest way to get it is to create a project base using the CLI. Then copy the vaadin-maven-plugin plugin from the downloaded POM file.

Note
Building for 64-Bit
If your operating system is 64-bit, be sure to use a 64-bit JDK installation, as well.

Excluding Development Server Module

The Vite server integration and live-reload features — which are available only during development — are contained in the module com.vaadin:vaadin-dev-server. You should exclude this module from production builds. You can do so by adding vaadin-dev dependency as a optional scope in project <dependencies>. Spring Boot 4 spring-boot-maven-plugin automatically excludes optional dependencies from the final build:

Source code
pom.xml
<dependencies>
    ...
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-dev</artifactId>
        <optional>true</optional>
    </dependency>
    ...
</dependencies>

This results in less code and fewer dependency libraries being bundled in the production application.

Transpilation & Bundling

Transpilation in Hilla means converting all TypeScript files to JavaScript, which is supported by modern browsers.

During the build, minimization is carried out to make the files smaller. When minifying code, it’s often obfuscated, making it harder to read. Therefore, this isn’t done during development.

Bundling is an optimization in which multiple files are merged into a single collection. This is so that the browser doesn’t need to request so many files from the server. As a result, the application usually loads faster.

Maven Plugin Goals & Goal Parameters

The build-frontend Goal

This goal builds the frontend bundle. It’s a complex process involving several steps:

  • Update package.json with all the @NpmPackage annotation values found in the classpath and automatically install these dependencies.

  • Update the JavaScript files containing code to import everything used in the application. These files are generated in the src/main/frontend/generated folder, and are used as the entry point of the application.

  • Create vite.config.ts, if it’s not found. Otherwise, update it if some project parameters have changed.

  • Generate JavaScript bundles and chunks and compile TypeScript to JavaScript using vite. The target folder for WAR packaging is target/${artifactId}-${version}/build; for JAR packaging, it’s target/classes/META-INF/resources/build.

This goal also has a few parameters. They’re listed here with their default values in parentheses, along with comments or a description of each:

npmFolder (${project.basedir}

The folder where the package.json file is located. The default is the project root folder.

generatedTsFolder (${project.basedir}/src/main/frontend/generated)

The folder where Vaadin puts generated files. If not given, will be generated folder under frontendDirectory parameter.

frontendDirectory (${project.basedir}/src/main/frontend)

The directory with the project’s frontend source files. The legacy location "${project.basedir}/frontend" is used if the default location doesn’t exist and this parameter isn’t set.

generateBundle (true)

Whether to generate a bundle from the project frontend sources.

runNpmInstall (true)

Whether to run pnpm install — or npm install, depending on the pnpmEnable parameter value — after updating dependencies.

generateEmbeddableWebComponents (true)

Whether to generate embedded web components from WebComponentExporter inheritors.

optimizeBundle (true)

Whether to include only frontend resources used from application entry points — the default — or to include all resources found on the classpath. It should normally be left to the default, but a value of false can be useful for faster production builds or debugging discrepancies between development and production builds.

pnpmEnable (false)

Whether to use the pnpm or npm tool to handle frontend resources. The default is npm.

useGlobalPnpm (false)

Whether to use a globally installed pnpm tool instead of the default supported version of pnpm.

forceProductionBuild (false)

Whether to generate a production bundle even if an existing pre-generated bundle could be used.

reactEnable (true)

Whether to use React Router, add React core dependencies, React integration helpers and Vaadin’s provided React components (@vaadin/react-components). Fallbacks to vaadin-router, excludes all React dependencies and adds Lit dependencies, if set to false.

frontendExtraFileExtensions (null)

Parameter for adding extensions of files to be stored in the stats.json of a generated bundle. For instance, if the project uses .scss files they are not automatically taken into account in the bundle hashes.

The clean-frontend Goal

This goal cleans frontend files that may cause inconsistencies when changing versions. Don’t add the goal as a default to pom.xml. Instead, use it with mvn vaadin:clean-frontend when necessary.

Executing the clean-frontend goal removes a few things:

  • the package lock file;

  • the generated frontend folder which is by default, src/main/frontend/generated; and

  • the node_modules folder — but this might need manual deletion.

The goal also cleans all dependencies that are managed by the framework, and any dependencies that target the build folder from the package.json file.

The clean-frontend goal supports the same parameters as build-frontend.