Docs

Docs

Build for Production

Create a JAR that runs in production mode, and understand what the build needs.

When you start a Vaadin application from your IDE, it runs in development mode, with live reload and other development tools. A production build creates an executable JAR that runs in production mode instead. It serves an optimized frontend bundle, and leaves the development tools out.

To build and start the application, run:

Source code
terminal
./mvnw clean package
java -jar target/*.jar

Then look for this line in the log:

Source code
Vaadin is running in production mode.

What the Build Does

The package phase compiles the application and runs its tests, so a failing test stops the build. The build-frontend goal of the Vaadin Maven plugin then prepares the frontend bundle, and marks the build for production mode. Finally, Spring Boot packages everything into a single JAR in the target directory.

Projects from start.vaadin.com are set up for this. If you created the pom.xml yourself, add the build-frontend goal, and make the vaadin-dev dependency optional, so that the JAR doesn’t include the development tools. See Enabling Production Builds and Excluding Development Server Module.

If the log says Vaadin is running in DEVELOPMENT mode instead, or the application fails to start, see Troubleshooting.

When the Build Needs Node.js

A Vaadin application needs a frontend bundle: the JavaScript and CSS of the UI components, and of any frontend code that the application adds. The build provides it in one of two ways:

  • A pre-compiled bundle. If the application uses only Vaadin’s UI components and themes, and loads its own stylesheets with @StyleSheet, the build uses a bundle that comes with Vaadin. It doesn’t need Node.js, and the build log says A production mode bundle build is not needed.

  • An application-specific bundle. If the application adds frontend code of its own — for example, an npm package, a JavaScript module, or an add-on with frontend code — the build runs npm and Vite to create a bundle for it. This needs Node.js and takes longer. The build log says A production mode bundle build is needed, and the line before it gives the reason.

The Production Build reference lists everything that requires an application-specific bundle.

An application-specific bundle is also written to src/main/bundles/prod.bundle. Commit this file. The next build reuses it, and doesn’t run npm or Vite at all, as long as the frontend code hasn’t changed. When the frontend code changes, the build notices it, and creates a new bundle. Commit that one, too.

When the Build Needs a License Key

If the application uses a commercial feature, the production build checks that you have a license for it. On a machine without a license key, such as a fresh build server, the build fails with the following message, followed by a list of the commercial features it found:

Source code
Commercial features require a subscription.

On your development machine, you get the key by logging in to your Vaadin account, as described in License Validation & Troubleshooting. To give the key to a build server, see Build on CI. To find out which features are commercial, see Licensing, Support & Maintenance.

Next Steps

The JAR contains the configuration that’s in src/main/resources/application.properties. Production needs different settings and secrets, which shouldn’t be in the source code. Configure the Application shows how to provide them.