Skip to content

docs: update articles for production build change #4650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 27, 2025
Merged

docs: update articles for production build change #4650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
978b681
docs: update articles for production build change
tltv Oct 10, 2025
c487657
Update quarkus.adoc
tltv Oct 14, 2025
f6c5afe
Update getting-started.adoc
tltv Oct 14, 2025
0048be7
Merge branch 'main' into docs/build-for-production-by-default
mshabarov Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion articles/flow/configuration/licenses/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The banner links to the https://vaadin.com/commercial-license-info[Commercial Li
[source,terminal]
----
<source-info group="Maven"></source-info>
mvn package -Pproduction -Dvaadin.commercialWithBanner
mvn package -Dvaadin.commercialWithBanner
----
[source,groovy]
----
Expand Down
4 changes: 2 additions & 2 deletions articles/flow/integrations/quarkus.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ After doing the <<quarkus.setup>>, the Quarkus application can be started in dev

[source,terminal]
----
mvn package quarkus:dev
mvn quarkus:dev
----

The application is then available at http://localhost:8080/[+localhost:8080+] in the browser.
Expand All @@ -212,7 +212,7 @@ When you're ready, run the following commands to start the application:

[source,terminal]
----
mvn package -Pproduction
mvn package
java -jar target/quarkus-app/quarkus-run.jar
----

Expand Down
2 changes: 1 addition & 1 deletion articles/flow/production/cloud-providers/aws/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Open the project directory from a terminal window, and enter the following comma

[source,terminal]
----
mvn package -Pproduction
mvn package
----

== Step 5: Initialize a Beanstalk Project
Expand Down
2 changes: 1 addition & 1 deletion articles/flow/production/cloud-providers/azure/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Open the project directory from a terminal window, and enter the following comma

[source,terminal]
----
mvn package -Pproduction
mvn package
----

== Step 5: Configure Your Application
Expand Down
2 changes: 1 addition & 1 deletion articles/flow/production/cloud-providers/google/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Finally, you can build and deploy using a single command as follows:

[source,terminal]
----
mvn package appengine:deploy -Pproduction
mvn package appengine:deploy
----

When the deployment has finished, the application URL is displayed in the logs.
Expand Down
2 changes: 1 addition & 1 deletion articles/flow/production/cloud-providers/heroku/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Open the project directory from a terminal window, and enter the following comma

[source,terminal]
----
mvn package -Pproduction
mvn package
----

== Step 5: Initialize a Heroku Application
Expand Down
2 changes: 1 addition & 1 deletion articles/flow/production/docker.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This approach makes building and running your container as simple as running the
+
[source,terminal]
----
mvn clean package -Pproduction
mvn clean package
----

. Run the following command to build your container:
Expand Down
90 changes: 80 additions & 10 deletions articles/flow/production/production-build.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,14 @@ order: 10

= Production Build

To create a production build, run the following from the command-line:
To create a production build, run the following from the command-line for application using Spring Boot:

[source,terminal]
----
mvn clean package
----

For other applications, e.g., Jakarta EE or plain Java, and for better backwards compatibility, run same with a production profile:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be easier to read if this can give a link to the fragment where the production profile is defined.


[source,terminal]
----
Expand Down Expand Up @@ -37,7 +44,7 @@ If needed, you can force the creation of an optimized production bundle by execu

[source,terminal]
----
mvn clean package -Pproduction -Dvaadin.force.production.build=true
mvn clean package -Dvaadin.force.production.build=true
----

[NOTE]
Expand All @@ -57,10 +64,62 @@ By default, Vaadin uses `npm install` to install frontend packages. This can be

When set, Vaadin interrupts package installation if it spots any mismatch between package versions in the [filename]`package.json` and the lock file. It'll then recommend re-running `npm install`. This makes production builds in the CI pipelines reproducible, enabling you to identify problems in advance.


== Enabling Production Builds

The production build command works out-of-the-box for Vaadin starter projects. It'll work with projects that are generated with `https://start.vaadin.com`. The starter projects come with the necessary Maven configuration. If you've manually created your project's [filename]`pom.xml` file, add the following Maven profile to enable production builds:
The production build command works out-of-the-box for Vaadin starter projects. It'll work with projects that are generated with `https://start.vaadin.com`. The starter projects come with the necessary Maven configuration.

If you've manually created your project's [filename]`pom.xml` file, add the following `vaadin-maven-plugin` to enable production builds when using Spring Boot:

.`pom.xml`
[source,xml]
----
<!--
.. configuration depending on environment ..
-->

<build>
<plugins>
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>prepare-frontend</goal>
</goals>
</execution>
<execution>
<id>package-for-production</id>
<goals>
<goal>build-frontend</goal>
</goals>
<phase>prepare-package</phase>
</execution>
</executions>
<configuration>
<!-- To always force an optimized production bundle build set this configuration to 'true' -->
<!-- To possibly use the pre-compiled production bundle remove or set to 'false' -->
<forceProductionBuild>true</forceProductionBuild>
<!-- To have reproducible build by running 'npm ci' -->
<ciBuild>true</ciBuild>
</configuration>
</plugin>
<!--
.. more plugins ..
-->
</plugins>
</build>
<!--
.. more configuration ..
-->
----

The content depends on the environment in which your application is running, but all variations call the Maven goal `vaadin:build-frontend`. The Maven goal `vaadin:prepare-frontend` is also required. Once the `vaadin:build-frontend` goal targeting `prepare-package` phase is added, you can call the production build command.

If you don't have the `build-frontend` goal in your [filename]`pom.xml` file, get a project base for Spring Boot projects from `https://start.vaadin.com`. Then copy the `vaadin-maven-plugin` plugin from the downloaded [filename]`pom.xml` file.

For other applications, e.g., Jakarta EE or plain Java, and for better backwards compatibility, add the following Maven profile to enable production builds and get a project base from `https://vaadin.com/hello-world-starters`:

.`pom.xml`
[source,xml]
Expand Down Expand Up @@ -106,12 +165,6 @@ The production build command works out-of-the-box for Vaadin starter projects. I
</profiles>
----

The content of the profile depends on the environment in which your application is running, but all variations call the Maven goal `vaadin:build-frontend`. The Maven goal `vaadin:prepare-frontend` is also required, but that's often declared already in the development build. Once the Maven profile is added, you can call the production build command.

If you don't have the production Maven profile in your [filename]`pom.xml` file, get a project base: for Spring Boot projects, get it from `https://start.vaadin.com`; for other stacks (e.g., Jakarta EE or plain Java) from `https://vaadin.com/hello-world-starters`. Then copy the production profile from the downloaded [filename]`pom.xml` file.

Having the production build as a separate Maven profile is recommended to avoid unexpected problems due to production settings during development.

.Building for 64-bit
[NOTE]
If you're using a 64-bit operating system, be sure to use a 64-bit JDK installation, as well.
Expand Down Expand Up @@ -146,6 +199,23 @@ The Vite server integration and live reload features -- which are available only
</profiles>
----

Or when building Spring Boot 4 application, add `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:

.`pom.xml`
[source,xml]
----
<dependencies>
...
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-dev</artifactId>
<optional>true</optional>
</dependency>
...
</dependencies>
----


Comment on lines +202 to +218
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd move this snippet to up (before a snippet with profile) so as to make it a primary recommended way for spring apps.

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


Expand Down
2 changes: 1 addition & 1 deletion articles/flow/testing/selenium.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ If you added your Selenium tests to a project that was generated from https://st

[source,terminal]
----
mvn verify -Pit,production
mvn verify -Pit
----

This runs the tests in the `it` profile, which starts the Spring Boot server before the tests are run -- and stops it afterwards. If you're running the test this way, your test classes must end with `IT`.
Expand Down
10 changes: 5 additions & 5 deletions articles/getting-started/build.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,26 +14,26 @@ Up to this point, the walking skeleton has been <<run#,running in development mo

== Make a Production Build

In the walking skeleton, you use the Vaadin Maven plugin to make a production build. You do this by activating the `production` profile, like this:
In the walking skeleton, you use the Vaadin Maven plugin to make a production build. You do this by activating the `package` goal, like this:

[.example]
--
[source,bash,subs="+attributes"]
----
<source-info group="macOS / Linux"></source-info>
./mvnw clean package -Pproduction
./mvnw clean package
----

[source,powershell,subs="+attributes"]
----
<source-info group="Windows"></source-info>
mvnw clean package -Pproduction
mvnw clean package
----
--

Once the build has finished, check the `target` directory. If your skeleton was named `my-application`, you should find a file called `my-application-1.0-SNAPSHOT.jar`.

The `production` profile not only builds the frontend, but also excludes the development server bundle since it contains features that aren't used in production.
The `package` goal not only builds the frontend, but also excludes the development server bundle since it contains features that aren't used in production.


== Build a Docker Image
Expand Down Expand Up @@ -107,7 +107,7 @@ RUN --mount=type=cache,target=/root/.m2 \
--mount=type=secret,id=offlineKey \
sh -c 'PRO_KEY=$(jq -r ".proKey // empty" /run/secrets/proKey 2>/dev/null || echo "") && \
OFFLINE_KEY=$(cat /run/secrets/offlineKey 2>/dev/null || echo "") && \
./mvnw clean package -Pproduction -DskipTests -Dvaadin.proKey=${PRO_KEY} -Dvaadin.offlineKey=${OFFLINE_KEY}'
./mvnw clean package -DskipTests -Dvaadin.proKey=${PRO_KEY} -Dvaadin.offlineKey=${OFFLINE_KEY}'
----

For more information about build secrets in Docker, see the https://docs.docker.com/build/building/secrets/[Docker documentation].
Expand Down
2 changes: 1 addition & 1 deletion articles/getting-started/walk-through.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,6 @@ The `spring-boot-maven-plugin` is used to package the application into a single,

The `vaadin-maven-plugin` is used to prepare and build the frontend files. Under the hood it is using link:https://www.npmjs.com/[npm] and link:https://vite.dev/[Vite].

The POM file defines one `production` build profile that triggers a production build, and is deactivated by default. You'll learn more about making a production build on the <<build#,Build a Project>> page.
The POM file triggers a production build by default. You'll learn more about making a production build on the <<build#,Build a Project>> page.

// TODO Write a guide about integration testing
87 changes: 38 additions & 49 deletions articles/hilla/guides/production/production-build.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,52 +13,52 @@ If you generated your application with Hilla CLI, you can create a production bu

[source,terminal]
----
mvn clean package -Pproduction
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 [filename]`pom.xml` file, add the following Maven profile to enable 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 [filename]`pom.xml` file, add the following `vaadin-maven-plugin` to enable production builds:

.pom.xml
[source,xml]
----
<profile>
<!-- Production mode is activated using -Pproduction -->
<id>production</id>
<build>
<plugins>
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>${vaadin.version}</version>
<executions>
<execution>
<goals>
<goal>build-frontend</goal>
</goals>
<phase>compile</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<build>
<plugins>
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>${vaadin.version}</version>
<executions>
<execution>
<goals>
<goal>prepare-frontend</goal>
</goals>
</execution>
<execution>
<id>package-for-production</id>
<goals>
<goal>build-frontend</goal>
</goals>
<phase>prepare-package</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
----

The actual content of the profile depends on the environment in which your application is running. However, all of the variants call the Maven goal `hilla:build-frontend`.


== Creating a Production Build

To create a production build, you can execute `mvn clean package -Pproduction`. 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.
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 production Maven profile in your `POM` file, the easiest way to get it is to create a project base using the CLI. Then copy the production profile from the downloaded `POM` file.

Having a production build as a separate Maven profile should help to avoid any unexpected problems during development, due to production settings.
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.

.Building for 64-Bit
[NOTE]
Expand All @@ -67,31 +67,20 @@ If your operating system is 64-bit, be sure to use a 64-bit JDK installation, as

== 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 the following dependency exclusion to the `<dependencies>` section in the `production` profile:
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:

.pom.xml
.`pom.xml`
[source,xml]
----
<profiles>
<profile>
<id>production</id>

<!-- above production build configuration -->

<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-core</artifactId>
<exclusions>
<exclusion>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-dev</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
</profile>
</profiles>
<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.
Expand Down
2 changes: 1 addition & 1 deletion articles/hilla/lit/guides/production/cloud-providers/aws/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Open the project directory from a terminal window, and enter the following comma

[source,terminal]
----
mvn package -Pproduction
mvn package
----

== Step 5: Initialize a Beanstalk Project
Expand Down
2 changes: 1 addition & 1 deletion articles/hilla/lit/guides/production/cloud-providers/azure/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Open the project directory from a terminal window, and enter the following comma

[source,terminal]
----
mvn package -Pproduction
mvn package
----

== Step 5: Configure Your Application
Expand Down
Loading