Deploying to Production

• Production Mode
• Spring Boot
• Jetty
• Cloud Providers

Deploying to a production server involves compiling and packaging the application to be suitable and optimized for the server.

While you may have used an embedded server during development, for production you need to deploy the application as a WAR (Java Servlet) or JAR (Spring Boot).

By default, Vaadin applications are set up to run in the development mode. This requires a bit more memory and CPU power, but enables easier debugging. When deploying your app to your users, you will want to switch to the production mode instead.

The main difference between the development and production modes is that in the development mode Vaadin uses Webpack to serve JavaScript files to the browser, instead of the Java server the app is running on. This is so that if you change a JS or CSS file, your changes are picked up and served automatically. When in production mode, you do not want this extra overhead since the files will not change; it is more efficient to prepare JavaScript and CSS files once, during build, and let one server (the Java Server) serve all requests. At the same time, the client resources can be optimized and minified to reduce the load on the network and browser even further.

Enabling Production Mode

The pom.xml file in a Vaadin project has the following built-in Maven configuration for creating a production mode build:

<profiles>
    <profile>
        <id>production</id>
        <properties>
            <vaadin.productionMode>true</vaadin.productionMode>
        </properties>
        <!--
        .. configuration depending on environment ..
         -->
         <executions>
             <execution>
                 <goals>
                     <goal>build-frontend</goal>
                 </goals>
                 <phase>compile</phase>
             </execution>
         </executions>
         <!--
         .. more configuration ..
         -->
    </profile>
</profiles>

The actual content of the profile will depend on what environment your app is running in, but all of the variations do two things:

1. Setting the property vaadin.productionMode to true

2. Calling the Maven goal vaadin:build-frontend

To create a production build, you can call mvn clean package -Pproduction. This will build a JAR or WAR file with all the dependencies and transpiled front end resources, ready to be deployed. The file can be found in the target folder after the build completes.

If you do not have the the production Maven profile in your POM file, the easiest way to get it is to get a project base from https://vaadin.com/start matching your environment (Spring boot, Jakarta EE, or plain Java), and copy the production profile from the downloaded POM file.

Having production mode be a separate Maven profile is recommended so that you do not get any unexpected problems due to production settings when running in the development mode.

Transpilation and Bundling

Transpilation in Vaadin means converting all ES6 JavaScript to ES5 JavaScript format for older browsers (IE11 and Safari 9). All Vaadin components are written using ES6, and consist of several JavaScript and CSS files. Transpilation makes sure this newer JavaScript code also works in older browsers, such as IE11.

During the build, minimization is done to make the files smaller. When minifying code, it is often obscured, which makes it harder to read, hence this is not done in the development mode.

Bundling is an optimization where we merge multiple files to a single collection so that the browser doesn’t need to request so many files from the server. This makes the application load faster.

Splitting the Webpack Bundle Into Multiple Chunks

This is an upcoming feature for a Vaadin Platform 14.x minor release, probably during 2020. For information on customizing bundling when using compatibility mode, see the Vaadin 13 documentation on this topic. You can follow & comment on https://github.com/vaadin/flow/issues/5537 if this is important for you.

Plugin Goals and Goal Parameters

Here we describe the maven plugin goals and their usage.

prepare-frontend

This goal validates whether the node and npm tools are installed and not too old (node version 10 or later and npm version 5.6 or later), and also installs them automatically to the .vaadin folder in the user’s home directory if they are missing. If they are installed globally but too old, there will be an error message suggesting to install newer versions instead. Node.js is needed to run npm for installing frontend dependencies and webpack which bundles the frontend files served to client.

In addition, it visits all resources used by the application and copies them under node_modules folder so they are available when webpack builds the frontend. It also creates or updates package.json, webpack.config.json and webpack.generated.json files.

Goal parameters

• includes (default: **/*.js,**/*.css): Comma separated wildcards for files and directories that should be copied. Default is only .js and .css files.

• npmFolder (default: ${project.basedir}): The folder where package.json file is located. Default is project root folder.

• webpackTemplate (default: webpack.config.js): Copy the webapp.config.js from the specified URL if missing. Default is the template provided by this plugin. Set it to empty string to disable the feature.

• webpackGeneratedTemplate (default: webpack.generated.js): Copy the webapp.config.js from the specified URL if missing. Default is the template provided by this plugin. Set it to empty string to disable the feature.

• generatedFolder (default: ${project.build.directory}/frontend/): The folder where Flow will put generated files that will be used by Webpack.

• require.home.node (default: false): Available since Vaadin 14.2. If set to true, always prefer Node.js automatically downloaded and installed into the .vaadin directory in the user’s home.

build-frontend

This goal builds the frontend bundle. This is a complex process involving several steps:

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

• update the JavaScript files containing code for importing everything used in the application. These files are generated in the target/frontend folder, and will be used as entry point of the application.

• create webpack.config.js if not found, or updates it in case some project parameters have changed.

• generate JavaScript bundles, chunks and transpile to ES5 using webpack server. Target folder in case of war packaging is target/${artifactId}-${version}/build and in case of jar packaging is target/classes/META-INF/resources/build.

Goal parameters

• npmFolder (default: ${project.basedir}: The folder where package.json file is located. Default is project root folder.

• generatedFolder (default: ${project.build.directory}/frontend/): The folder where Flow will put generated files that will be used by Webpack.

• frontendDirectory (default: ${project.basedir}/frontend): A directory with project’s frontend source files.

• generateBundle (default: true): Whether to generate a bundle from the project frontend sources or not.

• runNpmInstall (default: true): Whether to automatically run npm install or pnpm install(depending on pnpmEnable parameter value) after updating dependencies.

• generateEmbeddableWebComponents (default: true): Whether to generate embeddable web components from WebComponentExporter inheritors.

• optimizeBundle (default: true): Whether to include only frontend resources used from application entry points (the default) or to include all resources found on the class path. 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 mode. This configuration is available only in Vaadin Platform 14.1 and newer.

• pnpmEnable (default: false): Whether to use the pnpm or npm tool to handle frontend resources. By default npm is used. This configuration is available only in Vaadin 14.2 and newer.

Troubleshooting

After adding the flow-server-production-mode dependency, the application no longer starts

One likely cause of this problem is that the build-frontend of the flow-maven-plugin was not executed, either because the plugin is missing from the pom.xml or it is missing configuration. To fix this, add the flow-maven-plugin to your maven build block (make sure it is visible in your production mode profile), and enable the build-frontend goal.

Updated 2021-03-08  Edit this article