> Markdown version of [Starting a Vaadin Project with Gradle](https://vaadin.com/docs/v23/guide/start/gradle). Section index: [llms.txt](https://vaadin.com/docs/v23/guide/llms.txt)

# Starting a Vaadin Project with Gradle

Gradle is a popular build tool for Java, Groovy, Kotlin, and other projects. It’s an alternative to using Maven, and in many ways much simpler to use. It’s also more powerful, if that’s required. You can use it to build a Vaadin application, run it, and manage dependencies during development.

This tutorial describes how to create, compile, and run a Vaadin application using the Vaadin Gradle plugin. To run the application, the **Gretty plugin** is used to run it in an embedded web server.

For information about the general usage of Gradle, see the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html).

## <a id="requirements"></a>Requirements

To use the Vaadin Gradle plugin, your environment needs to meet the following requirements:

- Windows, Mac, or Linux

- Java SDK 11 or later

- Gradle 5 or 6 (optional, because of the provided wrapper in the starter projects)

  - If you prefer to install it directly, you can find the instructions at <https://gradle.org/install>

- Node.js and `npm` (optional, because they can also be installed locally to the project using the Vaadin Gradle plugin)

> **Note: Installing Gradle is optional**
>
> If you plan to use Vaadin’s Gradle-based starter projects, there is no need to install Gradle on your machine. A Gradle Wrapper script is included in those starter projects. This script manages the download and execution of Gradle locally for your project. For more information on using Gradle Wrapper, see the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html).

## <a id="creating-a-vaadin-project"></a>Creating a Vaadin Project

The easiest way to create a new project is to clone a starter repository containing an application skeleton.

You can also take any existing Vaadin project and make a `build.gradle` file for it, as described in ["The Build File"](#build-file).

### <a id="cloning-a-starter-repository"></a>Cloning a Starter Repository

The following starter repositories are currently available:

> **Note: Clone the master branch of the starter projects**
>
> The following repositories default to the V14 branch when you clone them. If you plan to use them with the latest version of Vaadin, there two options. You can either clone the master branch, or change to the master branch after you have cloned either of the starter projects.

- `https://github.com/vaadin/base-starter-gradle`

  A simple web application project to be deployed as a WAR package. This example can also be used for Java EE, by changing the servlet dependency to `javax:javaee-api` and perhaps also adding the dependency `com.vaadin:vaadin-cdi` for CDI integration.

  ```terminal
  git clone https://github.com/vaadin/base-starter-gradle my-project
  ```

- `https://github.com/vaadin/base-starter-spring-gradle`

  A web application project skeleton that uses Spring Boot.

  ```terminal
  git clone https://github.com/vaadin/base-starter-spring-gradle my-project
  ```

### <a id="starter-project-contents"></a>Starter Project Contents

When it has been cloned, the project should look as follows (imported into the Eclipse IDE):

[Image: Contents of a Gradle based project]

Cloned Starter Project

> **Note: Only the content of a simple web application starter is depicted**
>
> Only the contents of `base-starter-gradle` (a simple web application starter without Spring Boot) are presented in the preceding figure. However, the Spring Boot-based starter project is little different, except that it has an additional class annotated with `@SpringBootApplication`. If this is the first time you have and tried Vaadin with Spring Boot, see [Using Vaadin with Spring Boot](https://vaadin.com/docs/v23/integrations/spring/spring-boot.md) for more information.

The most important files and folders are as follows:

- `src/main/java/<package>/MainView.java`

  The application view class for the root route, built from components.

- `src/main/java/<package>/GreetService.java`

  A trivial service object to separate business data and logic from the view.

- `frontend/src`

  Folder for HTML templates and JavaScript code. See the `README` inside for more details.

- `frontend/styles/shared-styles.css`

  Application-specific style sheets to style the look of the application.

- `frontend/styles/vaadin-text-field-styles.css`

  An example to modify the style of the `TextField` component.

- `build.gradle`

  The Gradle build file as described later in [The Build File](#build-file).

- `gradlew` and `gradlew.bat`

  Gradle Wrapper build scripts for Linux/Mac (`gradlew`) and Windows (`gradlew.bat`). The build scripts enable the project to be built without having Gradle preinstalled. As the recommended way to execute any Gradle build is with the help of the Gradle Wrapper, we have also used `gradlew` instead of `gradle` throughout the documentation. However, the `gradlew` and `gradle` commands can be used interchangeably if you already have Gradle installed and you prefer to use your installed Gradle. You can find out more about the benefits of using Gradle Wrapper in the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html).

## <a id="build-file"></a>The Build File

As a minimum, the `build.gradle` file needs to enable the Vaadin Gradle Plugin:

```
plugins {
    id 'com.vaadin' version '20.0.0' (1)

    // Optional
    id 'org.gretty' version '3.0.3' (2)
    id 'war' (3)
    id 'groovy' (4)
}
```

1. Use the plugin version that matches the Vaadin version.

   <!-- vale Vale.Terms = NO -->

   See the releases at [github.com/vaadin/platform](https://github.com/vaadin/platform/releases) for the latest release.

   <!-- vale Vale.Terms = YES -->

   To try the pre-release version of the Vaadin Gradle plugin, see [Using plugin pre-release version](#pre-release)

2. Use the Gretty embedded web server to run the application during development. See [Running the Application](#running) for details.

3. Build a WAR package to deploy to a traditional servlet container. You also need to define the Servlet API using `providedCompile "javax.servlet:javax.servlet-api:3.1.0"` in the dependencies section.

4. By default, the plugin supports Java. You can include Groovy or Kotlin as an optional plugin.

### <a id="build-file.vaadin-options"></a>Vaadin Plugin Configuration

Vaadin Gradle plugin options are configured in a `vaadin` block.

For development, the block is usually like this:

```
vaadin {
    optimizeBundle = false
}
```

If the parameter is `true`, the front-end bundle is optimized for all supported browsers, but compilation is much slower.

For configuration options, see [plugin configuration options](#all-options)

### <a id="build-file.repositories"></a>Configuring Repositories

The `repositories` section defines the locations to search for packages. The repository that contains the Vaadin libraries is required as a minimum:

```
repositories {
    mavenCentral()
    maven { url = "https://maven.vaadin.com/vaadin-addons" }
}
```

If you want to try the Vaadin platform pre-release versions,you can add the following repository, as well:

```
repositories {
    maven { url = "https://maven.vaadin.com/vaadin-prereleases" }
}
```

> **Note: Vaadin recommends using final releases**
>
> To avoid any inconsistencies, don’t use any pre-release versions in your production environment, especially snapshots. Vaadin recommends using the latest major version. Visit the <https://vaadin.com/releases> page for the latest releases.

You can use any Gradle repository definitions in the block. See [Declaring repositories](https://docs.gradle.org/current/userguide/declaring_repositories.html) in the Gradle documentation for more information.

### <a id="build-file.dependencies"></a>Configuring Dependencies

You need to add the `vaadin-core` or `vaadin` library as a Java dependency:

```
dependencies {
    implementation "com.vaadin:vaadin-core:20.+"
}
```

When you specify a version of `20.+`, you are choosing to use the latest version of Vaadin, but you can also specify the exact version.

See [Declaring dependencies](https://docs.gradle.org/current/userguide/declaring_dependencies.html) in the Gradle documentation for further details.

### <a id="build-file.other"></a>Other Configuration

In the starter project, default targets are defined for convenience, so that you can run `gradle` without specifying any tasks:

```
defaultTasks("clean", "vaadinBuildFrontend", "build")
```

## <a id="compiling"></a>Compiling

If you have defined the default tasks as described earlier, in [Other Configuration](#build-file.other), you can run:

```terminal
./gradlew
```

on Windows:

```terminal
gradlew
```

> **Note: The Unix style of running gradlew is used for the rest of this document**
>
> To avoid unnecessary verbosity, only the Unix style of running `./gradlew` is used for the rest of this document. You need to replace it with `gradlew` if you are on a Windows machine.

Otherwise, the project builds with the standard `build` task. However, on the first build and also at other times when necessary, you need to build the Vaadin frontend.

```terminal
./gradlew vaadinBuildFrontend build
```

### <a id="compiling.tasks"></a>Vaadin Tasks

The Vaadin-related tasks handled by the plugin are as follows:

- `vaadinPrepareFrontend`

  Checks that Node.js and `npm` are installed, copies front-end resources, and creates or updates the `package.json` and Vite configuration files (`vite.config.ts` and `vite.generated.ts`). The front-end resources are inside `.jar` dependencies, and copied to `node_modules`.

- `vaadinBuildFrontend`

  Builds the front-end bundle with the `Vite` utility. Vaadin front-end resources, such as HTML, JavaScript, CSS, and images, are bundled to optimize loading the front-end. This task isn’t executed automatically on the `build` and other targets, so you need to run it explicitly.

- `vaadinClean`

  Cleans the project and removes `node_modules`, `package-lock.json`, `vite.generated.ts`, `tsconfig.json`, `types.d.ts`, `pnpm-lock.yaml` and `pnpmfile.js`. You need to run this task if you upgrade the Vaadin version, and in other similar situations.

To get the complete list of tasks handled by the configured plugins, enter:

```terminal
./gradlew tasks
```

## <a id="running"></a>Running the Application

You use a Spring Boot-based starter (Vaadin with Spring Boot) to run the application during development in a similar way to any normal Spring Boot application. This means you can run it either from the class containing the `main()` method (normally annotated with `@SpringBootApplication`), or by using Spring Boot’s Gradle plugin `bootRun` task:

```terminal
./gradlew bootRun
```

If you are using a simple web application (Vaadin without Spring Boot) to run the application during development, the Gradle plugin supports the Gretty plugin, which runs the application in an embedded web server. You can do this either in an IDE or at the command line.

One way to enable the Gretty plugin is in the `plugin` section of the `gradle.build` file, as in the starter project:

```
plugins {
    ...
    id 'org.gretty' version '3.0.3'
}
```

You can configure Gretty further in an optional `gretty` block:

```
gretty {
    contextPath = "/" (1)
    servletContainer = "jetty9.4" (2)
}
```

1. Sets the context path to the root path. The default context path contains the project name, so the URL would be `http://localhost:8080/myproject` (or whatever your project name is).

2. Use Jetty as the servlet container, with the specified version.

The application is started with the `appRun` task:

```terminal
 ./gradlew appRun
```

The task compiles the application and starts the web server in `http://localhost:8080/` (if the root context path is configured as described earlier).

You might need to add `jcenter()` to the list of repositories to be able to run Gretty tasks, depending on the situation at the time you are following this documentation. Some artifacts from `jcenter()` haven’t yet been moved to `mavenCentral()`. In the future, this step becomes unnecessary:

```
repositories {
    // should be removed in the future as jcenter() is obsolete.
    jcenter()
}
```

See the [Gretty documentation](https://akhikhl.github.io/gretty-doc/index.html) for a complete reference on using Gretty.

For issues when running the application in development mode, see [Known Issues](#known-issues) for possible solutions.

## <a id="developing-in-the-eclipse-ide"></a>Developing in the Eclipse IDE

Gradle has first-class support in the Eclipse IDE, IDEA, NetBeans, and Android Studio, among others. The following section describes creating, importing, and developing a Vaadin Gradle project in the Eclipse IDE.

### <a id="importing-a-new-project"></a>Importing a New Project

You create a new Vaadin project by cloning the repository on the command line and importing it to Eclipse as a Gradle project.

1. Clone the starter repository of your choice, as described earlier.

2. Select ****File** **›** **Import** **›** **Gradle** **›** **Existing Gradle Project****.

3. Enter or select the **Project root directory**.

4. Click **Finish**.

The project should appear in the **Project Explorer** and look as shown in [Cloned Starter Project](#newproject-image).

You should now see the **Gradle Tasks** tab. You can browse the available tasks.

[Image: Gradle Tasks tab in eclipse]

Gradle Tasks tab in Eclipse

### <a id="running-the-application"></a>Running the Application

You can run the project using Gretty in an embedded web server.

1. Open the **Gradle Tasks** tab

2. Double-click the `gretty` → `appRun` task

   - The **Gradle Executions** tab opens and shows the build progress

3. When the `:apprun` task is running, open `http://localhost:8080` in the browser.

4. To stop the server, go to the **Console** tab and press any key.

## <a id="production"></a>Going to Production

To build a web application as a WAR package, you need the `war` plugin. You also need to enable it.

In `build.gradle`, include the plugin and enable WAR build:

```
plugins {
  ...
  id 'war'
}

war {
    enabled = true
}
```

When doing a production-ready build, the Vaadin Gradle plugin transpiles the client-side dependencies to legacy browsers, as described in [Deploying to Production](https://vaadin.com/docs/v23/production.md). You enable this by either setting it in `build.gradle` or at the command line when invoking Gradle.

In `build.gradle`:

Enabling Vaadin production mode through `build.gradle`

```
vaadin {
   productionMode = true
}
```

At the command line:

Enabling Vaadin production mode through the command line

```terminal
./gradlew -Pvaadin.productionMode=true war
```

> **Note: Spring Boot-specific configuration**
>
> If you are using Vaadin with Spring Boot, the default packaging for production would normally be the `jar`. But, if you intend to package a Spring Boot application as a WAR to be deployed on a standalone container, such as `tomcat`, there are two additional steps you need to perform:

- Your application class that’s annotated with `@SpringBootApplication` should extend `SpringBootServletInitializer` and override the `configure()` method:

Example of enabling SpringBootServletInitializer

```java
@SpringBootApplication
public class DemoApplication extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(
	                     SpringApplicationBuilder application) {
        return application.sources(DemoApplication.class);
    }
}
```

- Adding the following dependency:

Dependency to be added to the `build.gradle`

```
dependencies {
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}
```

## <a id="pre-release"></a>Using Gradle Plugin Snapshot Versions

A snapshot version of the plugin is pushed to the pre-release repository. This section is about trying the pre-release and snapshot versions of the Vaadin Gradle plugin itself, not Vaadin.

To use the pre-release plugin, add the `vaadin-prereleases` repository to the project `settings.gradle` file. `settings.gradle` is mostly used within multi-module projects, but it comes in handy for other configurations, too. Thus, if you don’t already have it in your project, go ahead and create a plain text file called `settings.gradle` next to your `build.gradle` file (normally in the project root folder).

Plugin repository added to `settings.gradle` file

```
pluginManagement {
    repositories {
        maven { url = 'https://maven.vaadin.com/vaadin-prereleases' }
        gradlePluginPortal()
    }
}
```

The plugin then needs to be defined and applied in the `build.gradle` file.

Define the snapshot plugin

```
buildscript {
    ...
    dependencies {
        classpath group: 'com.vaadin',
                name: 'vaadin-gradle-plugin',
                version: '20.0-SNAPSHOT'
    }
}

plugins {
    ...
}

apply plugin: 'com.vaadin'
```

> **Note: Remember to update the plugins block**
>
> Remove the part `id 'com.vaadin' version 'xyz'` from the `plugins` block. The plugin is applied by specifying `apply plugin: 'com.vaadin'` (as demonstrated in the preceding file extract).

## <a id="all-options"></a>Plugin Configuration Options

Here are all the configuration options with their default values:

- `productionMode: Boolean = false`

  Indicates that the application is running in production mode. Defaults to `false`. For production, the frontend is transpiled for older browsers and optimized, as described in [Deploying to Production](https://vaadin.com/docs/v23/production.md). Running the `vaadinBuildFrontend` task automatically switches this to `true`, so there is no need to configure anything.

- `frontendOutputDirectory: File = null`

  The folder where Vite should output `index.js` and other generated files. Defaults to `null`, which uses the automatically detected value of the main SourceSet, usually `build/resources/main/META-INF/VAADIN/webapp/`.

- `npmFolder: File = project.projectDir`

  The folder where the `package.json` file is located. Defaults to the project root directory.

- `generatedFolder: File(project.projectDir, "target/frontend")`

  The target folder for generated files used by Vite.

- `frontendDirectory: File(project.projectDir, "frontend")`

  The directory with the front-end source files of the project.

- `generateBundle: Boolean = true`

  Set to `true` to generate a bundle from the project front-end sources.

- `runNpmInstall: Boolean = true`

  Run `npm install` after updating dependencies.

- `generateEmbeddableWebComponents: Boolean = true`

  Generate web components from `WebComponentExporter` inheritors.

- `frontendResourcesDirectory: File = File(project.projectDir, Constants.LOCAL_FRONTEND_RESOURCES_PATH)`

  Identifies the project front-end directory from where resources should be copied for use with Vite.

- `optimizeBundle: Boolean = true`

  Use byte code scanner strategy to discover front-end components.

- `pnpmEnable: Boolean = false`

  Use `pnpm` for installing `npm` front-end resources. Defaults to `false`.

- `useGlobalPnpm: Boolean = false`

  Use the globally installed `pnpm` tool or the default supported `pnpm` version. Defaults to `false`.

- `requireHomeNodeExec: Boolean = false`

  Force use of Vaadin home node executable. If it’s set to `true`, Vaadin home node is checked, and installed if absent. This is then be used instead of the globally or locally installed node.

- `useDeprecatedV14Bootstrapping: Boolean = false`

  Run the application in legacy V14 bootstrap mode. Defaults to `false`.

- `eagerServerLoad: Boolean = false`

  Add the initial User Interface Definition Language (UIDL) object to the bootstrap `index.html`. Defaults to `false`.

- `applicationProperties: File = File(project.projectDir, "src/main/resources/application.properties")`

  Application properties file in a Spring project.

- `openApiJsonFile: File = File(project.buildDir, "generated-resources/openapi.json")`

  Generated path of the OpenAPI JSON.

- `javaSourceFolder: File = File(project.projectDir, "src/main/java")`

  Java source folders for connect scanning.

- `generatedTsFolder: File = File(project.projectDir, "frontend/generated")`

  The folder where Flow puts TS API files for client projects.

- `nodeVersion: String = "v14.15.4"`

  The Node.js version to be used when Node.js is installed automatically by Vaadin, for example `"v14.15.4"`. Defaults to `[FrontendTools.DEFAULT_NODE_VERSION]`.

- `nodeDownloadRoot: String = "https://nodejs.org/dist/"`

  URL to download Node.js from. This can be needed in corporate environments where the Node.js download is provided from an intranet mirror. Defaults to `[NodeInstaller.DEFAULT_NODEJS_DOWNLOAD_ROOT]`.

- `nodeAutoUpdate: Boolean = false`

  Flag to enable automatic update of the Node.js version installed in `~/.vaadin` if it’s older than the default or defined `nodeVersion`.

- `resourceOutputDirectory: File = File(project.buildDir, "vaadin-generated")`

  The output directory for generated non-served resources, such as the token file. Defaults to `build/vaadin-generated`.

## <a id="known-issues"></a>Known Issues

### <a id="spring-boot"></a>Spring Boot

When the list of dependencies causes the classpath to go over a set limit on Windows, the build automatically generates a JAR containing a manifest with the classpath. Sometimes, when running a Spring Boot application, the resource loader doesn’t load the classpath packages correctly from the manifest. The failed annotation scanning makes the required `npm` packages unavailable.

You can fix this in two ways:

- add the repository `mavenLocal()` to [build file repositories](#build-file.repositories)

- specify the `vaadin.whitelisted-packages` property; see [Vaadin Spring Configuration](https://vaadin.com/docs/v23/integrations/spring/configuration.md)

`FA18F1BF-2C67-4CCF-85A2-C3E4D7AECFDB`