Build Tools: Maven & Gradle

A GWT application is three kinds of code that the Java tooling normally mixes together, and the build exists to keep them apart:

The running scenario of this section, the Bookshelf, is exactly this shape: bookshelf-shared, bookshelf-client and bookshelf-server as generated by the net.ltgt.gwt.archetypes:modular-webapp archetype, plus a small bookshelf-widgets library module added on this page to show a gwt-lib. The sources a GWT compile reads come from the module XML <source> paths, so the build must make the sources of dependencies available on the compiler classpath. gwt-maven-plugin does this with two packagings (gwt-lib and gwt-app) and a set of goals, described next.

Since 2.10.0 GWT publishes under the Maven groupId org.gwtproject (release notes 2.10.0); the former com.google.gwt coordinates stop at version 2.10.0. The bill of materials org.gwtproject:gwt:2.13.1 is a pom-type artifact that manages the versions of every GWT artifact, so that your POM states the GWT version exactly once:

Source: gwt-maven-plugin — Basic usage

Reading the 2.13.1 BOM (gwt-2.13.1.pom on Maven Central) gives the following picture. The version column is what the BOM pins; the last column says where the artifact belongs in the Bookshelf.

Source: org.gwtproject:gwt 2.13.1 — BOM POM on Maven Central

The BOM also pins third-party libraries that the tools use (gson, htmlunit, ASM, Jetty 9.4.58, icu4j, JDT), which is why they appear in a dependency:tree of any module that declares gwt-dev. A real excerpt, from the bookshelf-widgets module of this page (library with gwt-user at compile scope and gwt-dev at provided scope):

Source: org.gwtproject:gwt 2.13.1 — BOM POM on Maven Central

Two consequences matter in practice:

The Maven integration used by the archetypes, by the GWT project’s own samples (moved to Maven in 2.13.0) and by this section is net.ltgt.gwt.maven:gwt-maven-plugin, written by Thomas Broyer. Its design goals are stated on its site: it is independent of the GWT version (it passes explicit argument lists to GWT instead of modelling every flag), it understands multi-module projects, and it adds two packagings and two artifact types. It is tested against the latest two stable GWT versions and the latest snapshot.

Source: gwt-maven-plugin — Basic usage

<extensions>true</extensions> is what makes the gwt-app and gwt-lib packagings (and artifact types) known to Maven; without it Maven answers Unknown packaging: gwt-app. The usage page still shows BOM 2.13.0 while the plugin 1.3.0 is the latest release; use the BOM version you actually run. failOnError makes the compile fail when sources have errors instead of producing a partial result, and the generated POMs of both the archetype and webAppCreator set it. sourceLevel is explained under the compile goal.

The default project layout, which every goal assumes unless you reconfigure it:

Source: gwt-maven-plugin — Project layout

The plugin contributes two lifecycles, each triggered by a new <packaging>. They look like the jar and war lifecycles with different default bindings, and the bindings below are exactly those of the plugin’s Lifecycles page.

Source: gwt-maven-plugin — Lifecycles and Packagings

You can see the bindings working in a real run. This is mvn package -DskipTests for the bookshelf-widgets (gwt-lib) module; the lines that are not GWT goals are omitted:

Source: gwt-maven-plugin — gwt-lib lifecycle

The gwt-app module of the same build shows gwt:compile running at prepare-package and the output being packaged:

Source: gwt-maven-plugin — gwt-app lifecycle

The plugin has twelve goals (the plugin-info page and mvn gwt:help agree; help is the standard Maven plugin-plugin goal). mvn net.ltgt.gwt.maven:gwt-maven-plugin:1.3.0:help prints This plugin has 12 goals, and with -Ddetail=true -Dgoal=<name> the parameters of one goal.

Source: gwt-maven-plugin — Goals

gwt:codeserver and gwt:devmode are aggregator goals that require dependency resolution at compile+runtime scope and first execute the process-classes phase of the modules they run; the other goals resolve compile (compile), runtime (generate-module) or test (test) dependencies.

The three-module split is not decoration: it is how the plugin keeps the three code kinds apart. The Bookshelf reactor, in the order Maven resolves it from the dependencies, is bookshelf-widgets (gwt-lib), bookshelf-shared (jar), bookshelf-client (gwt-app) and bookshelf-server (war). The relationships to set up are:

Source: gwt-maven-plugin — Artifact Handlers

The shared module needs a sources classifier JAR (the client module lists it as a second dependency) because the compiler reads Java source; the maven-source-plugin execution jar-no-fork bound to package in the root pluginManagement produces it. A gwt-lib needs none of that because its JAR already contains sources, which is why a pure client library should be a gwt-lib and a library shared with the server should stay a plain JAR with sources.

The server module depends on the client’s WAR (<type>war</type>, runtime scope) and the maven-war-plugin overlays it:

Source: gwt-maven-plugin — gwt-app artifact

The archetype wraps that dependency in a profile pair. env-prod is active by default and adds the client WAR; env-dev is activated by -Denv=dev (or -Penv-dev, as the archetype README says) and instead points the Jetty plugin at the launcherDir written by the code server, so the server can be started without compiling the application. The comment in the generated POM explains the odd shape: Maven forces an explicit env-prod profile to be able to exclude the dependency in env-dev. The effect, measured on the Bookshelf, was that the server WAR built with -Denv=dev contained no nocache.js (0 matches), while the default build contained one:

Source: tbroyer/gwt-maven-archetypes — modular-webapp

The reactor options to remember are -pl (select projects), -am (also make the projects they depend on), -amd (also make the projects depending on them) and -rf (resume from). The first command above works because -pl bookshelf-client -am selects the client, the shared module and the library, and because the aggregator goal runs once at the root. In a shell, use plain project names, as noted before.

Compiling GWT is the slowest step of a CI job (17 seconds for the small Bookshelf, minutes for a real application), and most jobs do not need it: a server-only test run, a lint job, or a documentation job. Because the plugin parameters are bound to properties, a profile can switch work off without editing any plugin configuration.

Source: Apache Maven — Introduction to Build Profiles

Run with -Pno-gwt the whole reactor built in 3.4 seconds, all four modules SUCCESS, with the log lines GWT compilation is skipped for the client and Tests are skipped. for each module. That is the right profile for a job that only needs to know that the Java sources compile. The ci-fast profile keeps the compile but cuts its cost; it is suitable for pull-request builds that run the browser tests, while the release build runs without it so that the shipped JavaScript is optimised and obfuscated. Guidelines that follow from the descriptor:

Source: gwt-maven-plugin — gwt:compile skipCompilation

The Maven commands of the fragment were run as shown; the workflow file itself was not executed.

A library that other GWT projects will inherit must ship its sources, because the consumer’s compiler translates them. The module descriptor and any public resources must be on the classpath next to them. Doing this by hand means placing src/main/java in the resources (or building a second JAR with the maven-source-plugin and a sources classifier, as the shared module does) and writing the .gwt.xml correctly. The plugin automates the first variant, which is why a gwt-lib is the recommended packaging for client-only libraries:

The consumer needs no <inherits> line when it uses gwt:generate-module, because META-INF/gwt/mainModule from the direct dependency generates it, and it needs one if the module template is hand-written and generation is skipped. A library that is not a gwt-lib but publishes a sources classifier is consumed as in the Bookshelf’s bookshelf-shared: both the binary and the sources dependency, and <inherits> of the module (or the mainModule mechanism when the producer uses gwt:generate-module-metadata).

What goes wrong is nearly always one of two things, both visible as compiler errors: the sources are not on the classpath (No source code is available for type com.example.bookshelf.shared.Book; did you forget to inherit a required module?), or the module is not inherited. The next pitfall table collects them. The module XML itself (the <source>, <public> and <inherits> elements and the standard module hierarchy) is explained on the Project Structure & Modules page; the official reference is the Developer Guide chapter on modules.

Source: GWT — Organizing Projects: Modules, units of configuration

Before Thomas Broyer’s plugin, the Maven plugin for GWT was org.codehaus.mojo:gwt-maven-plugin (goal prefix gwt, the same prefix, which makes it easy to confuse the two). Its last release is 2.10.0 (the Maven Central metadata was last updated on 2022-06-25), and its build properties show it was built against GWT 2.10.0 (gwt.version). It is tied to one GWT version, which is the root of most migration work. Its goals, read from the plugin.xml of the 2.10.0 JAR:

Source: Codehaus (mojo) gwt-maven-plugin — site

Goals such as generateAsync, i18n, css, mergewebxml and eclipse have no equivalent in the new plugin; the plugin’s migration page says that most goals of the old plugin have none. The differences it lists are:

Source: gwt-maven-plugin — Migrating from Mojo’s Maven Plugin for GWT

A practical migration order that keeps the project building at every step:

A concrete failure reproduces the skipModule pitfall. When the library module had skipModule set to true but no descriptor under target/classes, gwt:codeserver at the root failed with:

Source: gwt-maven-plugin — gwt:generate-module skipModule

Take care with the groupId during the move: GWT’s coordinates changed from com.google.gwt to org.gwtproject at 2.10.0, so an old POM that declares com.google.gwt:gwt-user:2.10.0 still resolves, but nothing newer is published there.

GWT itself has no official Gradle plugin and no Gradle page in its documentation: the Developer Guide, the Getting Started page and the release notes mention Ant and Maven only. Gradle support is entirely community maintained. The state of the plugins on 2026-10-08, read from the Gradle Plugin Portal and the project repositories:

Source: jiakuan/gwt-gradle-plugin — README, esoco/gwt-gradle-plugin — README

The minimal setup of the first plugin, as its README documents it:

Source: Gradle Plugin Portal — org.docstr.gwt

I did not run either Gradle plugin, so nothing about their task behaviour or compatibility with the Bookshelf is claimed beyond what the READMEs say. If you choose Gradle, the equivalent of the multi-module layout above is a client project that applies the GWT plugin, a shared project that exposes its sources to the client, and a server project; check how the plugin you pick makes the sources of the shared project available to the compiler, since that is the part Maven solves with the sources classifier and gwt-lib. Maven remains the build documented and exercised throughout this section, because gwt-maven-plugin, the archetypes and the GWT project’s own samples are Maven.

Before archetypes, the GWT SDK shipped command-line generators. They are history, and the official pages that still describe them have not kept up.

webAppCreator is a script in the SDK that runs com.google.gwt.user.tools.WebAppCreator from gwt-user. Its documented parameters are -[no]overwriteFiles, -[no]ignoreExistingFiles, -templates (default sample,ant,eclipse,readme), -out, -junit, the deprecated -[no]maven and -[no]ant, and the module name. The 2.11.0 release notes list the tool as deprecated. The class itself prints this on every run (real output on 2.13.1):

Source: GWT — Command Line Tools: webAppCreator

Source: GWT — Command Line Tools: webAppCreator

What it generates is a single-module war project, the opposite of the layout recommended above. Its pom.xml (2.13.1) still pins gwt-maven-plugin 1.2.0, runs the compile and test goals, sets maven.compiler.release to 11 and sourceLevel to 11, writes the classes into WEB-INF/classes and disables Surefire in favour of gwt:test. It passes -compileReport and -XcompilerMetrics in compilerArgs (see Compile Reports & Optimization); the latter is accepted by the compiler but is not listed in the compiler’s -help output. The official Getting Started page (gettingstarted.html) still tells you to unpack gwt-2.10.0.zip, requires Java 1.8 and Apache Ant, and uses the default Ant template with ant devmode and ant build, so it is stale; the same is true of the Compile & Debug chapter, which launches DevMode through ant devmode. The deprecation, not those pages, is current. Use the archetype instead:

Source: tbroyer/gwt-maven-archetypes

i18nCreator (com.google.gwt.i18n.tools.I18NCreator) generates a properties file and a script that regenerates the Java interface (a Constants, ConstantsWithLookup or Messages subinterface) when the properties change. It is not deprecated in the source and still runs. Real output for a Messages interface:

Source: GWT — Command Line Tools: i18nCreator

The generated script calls com.google.gwt.i18n.tools.I18NSync with the classpath of the machine where it was generated, which makes it non-portable. The Internationalization page recommends writing the Messages interface first and the properties files from it, which is the direction Maven builds prefer.

Source: gwt-maven-plugin — gwt:test