Documentation

Documentation

Development Mode

Develop applications faster with a live-reload, frontend development server.

Vaadin Flow’s Development Mode makes application development faster by enabling easier debugging with a live-reload, frontend development server, and helpful debugging tools. Vaadin applications can run in two modes: development mode; or production mode.

Development mode is designed to make it easier to build applications. Changes you make to a project are detected automatically, refreshing the browser to display the new page and application. Included in the data sent to the browser is information to help troubleshoot any problems. It provides such information and helpful debugging tools through the browser’s development tools window.

The amount of data sent when in Development mode, though, is not optimized to be small. Conversely, Production mode sends as little data as possible to the end user’s browser. It optimizes performance wherever possible. In this mode, no development tools are used, and debugging information is disabled.

Development Mode Methods

When in development mode, you have two choices or methods for utilizing this mode: use a Pre-Compiled Frontend Bundle; or use a Frontend Development Server. The difference between these methods is in how the frontend files are handled.

When using a pre-compiled frontend bundle, the frontend files are collected and compiled into a bundle and are served similarly to the browser as when in production mode. The difference is that debugging features are enabled.

When running with the frontend development server, JavaScript and CSS and other frontend files are served by it and given individually to the browser as requested — instead of the application’s Java server handling such requests.

Faster Starts by Pre-Compiling

The build and start-up time can be decreased significantly if no frontend installation or compilation is made. This means not installing the tools Node.js, npm/pnpm/bun. It also means not having to download npm packages, or running the Vite development server.

If your project uses only the standard Vaadin Flow components or third-party Vaadin add-ons (e.g., from the Vaadin Directory) without client code, Vaadin skips frontend compilation and uses the default themes and frontend files shipped with the Vaadin platform.

Adding any custom JavaScript/TypeScript or add-ons with frontend customizations to a project can trigger the frontend re-compilation using Vite the next time the application is started. Any new or missing frontend packages are downloaded using npm/pnpm/bun before building. Vaadin does this automatically, and spots the frontend customizations.

Making a new frontend bundle takes time. However, the generated frontend files are compressed to the src/main/bundles/prod.bundle file inside the project’s root. This file can be added to the Version Control System, which allows other developers to fetch the application bundle and thereby run it.

The actual bundle files go to the build directory (i.e., target for Maven, build for Gradle) and are used from there. This way minor changes don’t cause multiple files to change and be committed to the Version Control System.

The application bundle is the same as the default bundle, but it’s made for a specific application. Vaadin defines two origins for the frontend development bundle: the "default" bundle updated and provided by the Vaadin platform in each release version; and the "application" bundle, which is made by locally running the project and taking into account the specific frontend customizations.

Vaadin generates an application bundle in the following situations:

  • An npm package is added with @NpmPackage, or directly into package.json;

  • CSS or JavaScript is added with @CssImport, @JsModule, or @JavaScript;

  • Vaadin add-on with frontend customizations is added;

  • Custom theme packaged as a JAR dependency is added, if it defines any assets to be added to the project; or

  • Exported web component is added.

Custom theme files are served separately from the frontend bundle. They can be modified on the fly; the browser live-reload refreshes the page immediately — no re-compilation is needed.

When customizing an Application Theme in this mode, the following points should be taken into account:

  • Loading CSS into the shadow DOM of Vaadin components by placing them in the theme’s components sub-folder requires the running of a frontend development server.

  • Vaadin component styles are set in styles.css, or in the imported stylesheet file located in the theme directory, with the ::part() selector.

  • Use the assets block in the theme.json file to specify the external assets — fonts, images, or stylesheets — to be added to the application development bundle, so that they can be used in the application.

  • Use Vaadin Line-Awesome add-on that doesn’t require building a new bundle.

This is the default mode.

Easier Debugging

When working with a frontend heavy project, there can be a frontend development server running for fast compilation and live-reload when the frontend files are changed.

Vaadin uses Vite to quicken frontend development by enabling the client-side live reload. By doing this, JavaScript/TypeScript changes are updated immediately in the browser. Vite only re-compiles what has changed, making hot reloads fast.

Vite installation is made through npm/pnpm/bun. Running Vite requires Node.js. See Node.js installation and Configuring frontend package manager for more information.

This mode is recommended if components or views use Templates and are edited often. This mode is used when the configuration parameter frontend.hotdeploy is set to true (see Configuration Properties for more information).

Disabling the Pre-Compiled Bundle

One of the following methods can be used to disable the pre-compiled frontend bundle, and use instead the frontend development server, depending on the project’s setup:

vaadin.frontend.hotdeploy=true

Vaadin allows this to prevent the frontend development bundle from being re-built even if it decides to use an existing compiled development bundle. This might be needed when re-bundling checker in Flow has issues leading to a false re-bundling and one needs a workaround while the problem is being resolved:

-Dvaadin.skip.dev.bundle=true

Topics

Node.js
Installing and using Node.js locally and in CI servers.
npm/pnpm/bun
Configuring the frontend package manager.
Development Tools
Vaadin tools available when running applications in development mode.