Documentation

Documentation

Flow-Hilla Hybrid Applications

Create hybrid applications by combining Hilla/React views with Flow views.

Hilla is a framework by Vaadin for building reactive web applications on Java backends. It seamlessly integrates a React TypeScript frontend with a Spring Boot backend.

You can develop hybrid applications that leverage Vaadin Flow and Hilla. This allows you to combine Vaadin Flow routes written in pure Java with the Hilla ones written in React, all in one application.

This guide demonstrates how to add Hilla to an existing Vaadin Flow application, or add Vaadin Flow to an existing Hilla application.

See the source code of a complete Vaadin Flow-Hilla application.

Add Hilla to Flow Applications

To add Hilla to a Vaadin Flow application, for example, you could start with a Spring Boot-based Vaadin Flow application (e.g., skeleton-starter-flow-spring). You can add Hilla to the project using the steps described in the sub-sections here.

Adjust Project Dependencies

You’ll need to make some adjustments to your pom.xml file. First, add the hilla.version property to the <properties> section like so:

 <properties>
     <!-- ... -->
+    <hilla.version>2.5.1</hilla.version>
 </properties>

Next, add the hilla-bom dependency to the <dependencyManagement> section like this:

 <dependencyManagement>
     <dependencies>
         <!-- ... -->
+        <dependency>
+            <groupId>dev.hilla</groupId>
+            <artifactId>hilla-bom</artifactId>
+            <version>${hilla.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
     </dependencies>
 </dependencyManagement>

Now, add the hilla-react dependency and replace the vaadin-spring-boot-starter dependency with the hilla-react-spring-boot-starter one:

 <dependencies>
     <!-- ... -->
-    <dependency>
-        <groupId>com.vaadin</groupId>
-        <artifactId>vaadin-spring-boot-starter</artifactId>
-    </dependency>
+    <dependency>
+        <groupId>dev.hilla</groupId>
+        <artifactId>hilla-react-spring-boot-starter</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>dev.hilla</groupId>
+        <artifactId>hilla-react</artifactId>
+    </dependency>
     <!-- ... -->
 </dependencies>

Last, replace all vaadin-maven-plugin instances with hilla-maven-plugin:

     <plugin>
-        <groupId>com.vaadin</groupId>
-        <artifactId>vaadin-maven-plugin</artifactId>
-        <version>${vaadin.version}</version>
+        <groupId>dev.hilla</groupId>
+        <artifactId>hilla-maven-plugin</artifactId>
+        <version>${hilla.version}</version>
         <executions>
             <execution>
                 <goals>
     <!-- ... -->

Enable React Router Feature Flag

React integration for Vaadin Flow is under development. Therefore, it’s behind a feature flag. Enable the React router feature flag by adding the following parameter to the src/main/resources/vaadin-featureflags.properties file — or create the file if it doesn’t exist:

com.vaadin.experimental.reactRouter=true

Add Hilla Frontend Files

Next, run mvn hilla:init-app from the command line to generate these Hilla-specific files:

  • package.json

  • package-lock.json

In the frontend/ sub-directory, you’ll also find these files:

  • App.tsx

  • routes.tsx

  • index.ts

  • views/MainView.tsx

In frontend/routes.tsx, add the serverSideRoutes object to the routes array:

+ import {serverSideRoutes} from "Frontend/generated/flow/Flow";
 // Other imports

 export const routes = [
   // Hilla definitions
+  ...serverSideRoutes
 ]

Adding serverSideRoutes is required for React Router to be able to navigate to server-side (i.e., Vaadin Flow) routes. If this configuration is missed and the feature flag is enabled, Vaadin throws a runtime exception at build time.

Use SideNav or Anchor components to navigate from a Flow view to a Hilla view:

Anchor navigateToFlow = new Anchor("hilla", "Navigate to a Hilla view");

Run the Application

Run the application using mvn spring-boot:run and open http://localhost:8080 in your browser.

Add Flow to Hilla Applications

If you already have a Hilla application, you can add Vaadin Flow to it. For example, starting from this Hilla project starter), you can add Vaadin Flow to the project using the steps in the sub-sections that follow.

Adjust Project Dependencies

Open your pom.xml file and add the necessary dependencies for Vaadin Flow:

 <properties>
+    <java.version>17</java.version>
+    <vaadin.version>24.3.0</vaadin.version>
     <!-- ... -->
 </properties>

 <dependencyManagement>
     <dependencies>
+        <dependency>
+            <groupId>com.vaadin</groupId>
+            <artifactId>vaadin-bom</artifactId>
+            <version>${vaadin.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
         <dependency>
             <groupId>dev.hilla</groupId>
             <artifactId>hilla-bom</artifactId>
             <version>${hilla.version}</version>
             <type>pom</type>
             <scope>import</scope>
         </dependency>
         <!-- ... -->
     </dependencies>
 </dependencyManagement>

Then add the vaadin-core or vaadin dependency:

 <dependencies>
     <!-- ... -->
+    <dependency>
+        <groupId>com.vaadin</groupId>
+        <!-- Replace artifactId with 'vaadin-core' to use only free components -->
+        <artifactId>vaadin</artifactId>
+    </dependency>
 </dependencies>

Enable Feature Flag

Enable the React router feature flag by adding the following parameter to src/main/resources/vaadin-featureflags.properties:

com.vaadin.experimental.reactRouter=true

Add Server-Side Routes Target

In the frontend/routes.tsx file, import and include the serverSideRoutes object:

+import {serverSideRoutes} from "Frontend/generated/flow/Flow";
 // Other imports

 export const routes: RouteObject[] = [
     // ...
+    ...serverSideRoutes
 ]

The following is an example of a routes.tsx file based on the Hilla Customer Relationship Management (CRM) Tutorial

import { serverSideRoutes } from "Frontend/generated/flow/Flow";
import MainLayout from 'Frontend/views/MainLayout';
import ContactsView from 'Frontend/views/ContactsView';
import AboutView from 'Frontend/views/AboutView';
import { RouteObject } from 'react-router-dom';

export const routes: RouteObject[] = [
    {
        element: <MainLayout />,
        handle: { title: 'Hilla CRM' },
        children: [
            { path: '/', element: <ContactsView />, handle: { title: 'Contacts' } },
            { path: '/about', element: <AboutView />, handle: { title: 'About' } },
            ...serverSideRoutes
        ],
    },
];

Adding serverSideRoutes is required for React Router to be able to navigate to server-side (i.e., Vaadin Flow) routes. If this configuration is missed and the feature flag is enabled, Vaadin throws a runtime exception in build time.

Note
Route Configuration & React Dependencies
Vaadin creates frontend/App.tsx and frontend/routes.tsx files if they are missing, as well as the internal Frontend/generated/flow/Flow.tsx file. Also, React dependencies — such as react, react-dom and react-router-dom — are added to the package.json file and installed.

Use Vaadin’s SideNav or React’s NavLink / Link components to navigate from a Hilla view to a Flow view:

import { NavLink } from 'react-router-dom';

<NavLink to="/flow-route">Navigate to a Flow View</NavLink>

9da82521-5074-42b6-82a5-88fc207987d0