Vaadin Production Build Bundle and Deploy Step by Step
Build a Vaadin application for production with the production profile, produce the frontend bundle, package a jar or image and verify it.

A Vaadin application runs in two modes. In development mode a dev server compiles the frontend on demand and reloads the browser, which is convenient and slow to start. In production mode the frontend is compiled once at build time into a minified, hashed bundle that is packed into the jar, and the application serves it as static files. The switch between the two is one Maven profile, and the failure when you skip it is a page that loads blank. This post covers the build, the artifact, a container image, proxy settings and a check to run before shipping. It uses Vaadin 25, Spring Boot 4 and JDK 25.
The production build
./mvnw -Pproduction clean packageThe production profile is part of the project that start.vaadin.com generates. It sets the vaadin-maven-plugin goals prepare-frontend and build-frontend, and adds the dependency that switches the runtime to production mode. If your project was created by hand, add the profile yourself, following the Vaadin production documentation:
<profile>
<id>production</id>
<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-core</artifactId>
<exclusions>
<exclusion>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-dev</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>prepare-frontend</goal>
<goal>build-frontend</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>The build needs Node.js. The plugin downloads a private copy on first use into ~/.vaadin, so the first production build on a clean CI agent takes minutes and needs network access to npm. Cache ~/.vaadin and node_modules between CI runs, and the build drops to a fraction of that. In an air-gapped network, point npm at an internal registry through the project's .npmrc.
The output is target/shop-1.0.jar, a standard Spring Boot jar that contains the compiled bundle under META-INF/VAADIN/webapp. Production mode turns off the dev server, minifies the code, adds content hashes to file names so browsers cache them correctly, and disables the debug tooling. Build the bundle from the same dependency set you deploy, because a bundle compiled against one version of a component and a server running another is a mismatch the build will not warn you about.
The Gradle equivalent
plugins {
id 'com.vaadin' version '25.0.0'
}
vaadin {
productionMode = true
}With the plugin applied, ./gradlew build -Pvaadin.productionMode produces the bundle and bootJar packs it. Set productionMode from the property in CI and leave it off locally, so day-to-day runs use the dev server.
Run the artifact
java -jar target/shop-1.0.jarOpen the page and look at the network tab: files with hashes in the name (index-3f8a1c.js) are served from /VAADIN/build. If you see requests to /VAADIN/@vite or a websocket for hot reload, the jar is still in development mode. The log line Vaadin is running in production mode confirms the other direction. The jar is self-contained and needs only a JRE of the version you built for.
A container image
FROM eclipse-temurin:25-jdk AS build
WORKDIR /src
COPY . .
RUN ./mvnw -Pproduction -DskipTests clean package
FROM eclipse-temurin:25-jre
RUN useradd --system --uid 10001 app
USER app
COPY --from=build /src/target/shop-*.jar /app/shop.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/shop.jar"]A multi-stage build keeps the Node toolchain and the Maven cache out of the final image, see multi-stage builds. The builder stage downloads Node on every build unless you mount a cache; with BuildKit, RUN --mount=type=cache,target=/root/.vaadin avoids it. Running as a non-root user is covered in writing a Dockerfile. The image contains no frontend source, only the jar.
Build time, size and caching
Expect a production build to take one to three minutes on a warm cache and longer on a cold agent, mostly in npm and the bundler. The jar is larger than a typical Spring Boot jar, because the bundle carries the component set your views use. If the size matters, look at which components the application imports, since unused ones are not tree-shaken away in every case.
The hashed file names mean the browser caches bundle files indefinitely, and a new release changes the names, so users get the update on the next page load with no manual cache clearing. Do not put a CDN rule in front that caches index.html for a long time, or users keep an old entry file that points at deleted bundle files, and the page turns blank until the cache expires. Set Cache-Control: no-cache on the HTML entry point and let the hashed assets cache for a year.
Behind a proxy
Vaadin builds absolute URLs for redirects and for the push connection, so it must know the public address. Behind a load balancer that terminates TLS, set the forwarded header strategy:
server.forward-headers-strategy=framework
server.servlet.session.timeout=30m
vaadin.heartbeatInterval=300Without it, a login redirect may send the browser to http:// and the application's internal port. With push enabled, the proxy must pass WebSocket upgrades and keep idle connections longer than the heartbeat interval. Stateful sessions need sticky routing on a multi-node deployment, because each UI lives in the memory of one server; alternatively, store sessions in Redis with Spring Session and accept the serialisation cost.
Verify before shipping
Run the artifact, not the IDE. In a clean directory, start the jar with a production profile, request the root page with curl -I, and load it once in a browser with the console open. Check that no 404 appears for /VAADIN/ files and that no errors are logged. Automate the check as a smoke test in the pipeline that starts the container and requests the page, so a missing bundle fails the build and not the release. A blank page after deployment, with a working page locally, is almost always the bundle, as described in fixing the blank page.
Custom components and the bundle
Components you write in TypeScript or with @JsModule are compiled into the same bundle during build-frontend. A missing import that happened to work with the dev server's module resolution can fail the production build, which is a useful early warning. The authoring side is in custom components, and the starting point is the beginner tutorial.
Checking the bundle size
After the first production build, look at the size of the jar and of the files under META-INF/VAADIN/webapp/VAADIN/build. A bundle that is much larger than expected usually includes a component library you imported for one widget. The build writes a stats file you can open in a bundle analyser to see which modules dominate. Trimming the imports of unused components is the one place where a production build rewards attention, since every kilobyte is downloaded by every first-time visitor.
Where this does not apply
If you deploy a WAR to an external servlet container, the same bundle is built, and the differences are in the packaging and context path. If you run the application behind a path prefix, set server.servlet.context-path and check that static resources resolve. The deployment advice for the jar is in the Spring Boot deployment guide, and the frontend build options are in the Vaadin production documentation.


