Getting Started

The root POM is the one place where versions live. It imports the GWT BOM, pins the Jakarta Servlet API, and sets the plugin versions:

Source: gwt-maven-plugin — Basic usage

Three details are worth reading closely:

The client POM depends on the shared module twice, as a jar (for javac) and with the sources classifier (for the GWT compiler), and on gwt-user and gwt-dev. The plugin configuration names the module:

Source: gwt-maven-plugin — gwt:compile

moduleName is the fully qualified name of the GWT module (the App module in package com.example.bookshelf), and moduleShortName is the name given to the output script, so the browser loads bookshelf/bookshelf.nocache.js. The plugin documentation describes it as "the short name of the module, used to name the output .nocache.js file".

The shared module’s only dependency is gwt-servlet-jakarta with provided scope (it needs the RPC interfaces) and the maven-source-plugin to attach the sources jar at the package phase. The server module is a war that depends on the shared module and on gwt-servlet-jakarta, and on jakarta.servlet-api as provided. Its two profiles are the key to the development loop:

Source: tbroyer/gwt-maven-archetypes — Profiles

In the default env-prod profile the server war overlays the compiled client war, so one deployable archive contains the host page, the JavaScript and the servlets. With -Denv=dev (or -Penv-dev) the env-dev profile is active instead: the client dependency disappears, and Jetty serves the static files of the server module plus whatever the code server wrote into launcherDir. The archetype’s README explains it the same way: env-dev "configures the Jetty plugin and removes the dependency on the client module".

The module XML is bookshelf-client/src/main/module.gwt.xml. It is a source file for the plugin, not the finished module:

Source: GWT — Organizing Projects: Module XML Files

The gwt:generate-module goal processes it into target/classes/com/example/bookshelf/App.gwt.xml, adding the rename-to attribute from moduleShortName. This is the generated copy, as it was produced by the build:

Source: gwt-maven-plugin — Project layout

What each line does:

The reference for every element, and for inheriting, overriding and super-sources, is Project Structure & Modules.

The host page is the HTML page that loads the compiled script. The generated one is bookshelf-server/src/main/webapp/index.html. The important parts are a standards-mode doctype, one <script> that loads bookshelf/bookshelf.nocache.js, and elements with ids that the code attaches widgets to. This version is the one the page uses from here on (the archetype’s own file also contains a table for the greeting sample):

Source: GWT — Organizing Projects: The Host Page

The *.nocache.js file is a tiny bootstrap that is never cached: it decides, from the browser’s properties, which permutation to load, and then loads the matching *.cache.js file, which is cacheable forever because its name is a hash of its content. Compiler & Compilation explains that selection in detail (see also Linkers & Bootstrap). In Super Dev Mode the same file name is served from launcherDir and asks the code server for a fresh compile instead.

An entry point is a class that implements com.google.gwt.core.client.EntryPoint, which has one method, onModuleLoad(). The Javadoc says the method is "called automatically by loading a module that declares an implementing class as an entry point", which happens once, in the browser, after the script has loaded. A module may name several <entry-point> classes, including ones from inherited modules; the Developer Guide says they are called sequentially in the order they appear in the module file, each as soon as the previous onModuleLoad() returns. The archetype’s App class builds a button, a text field and a dialog for a greeting call to the server. The Bookshelf replaces it with the first real screen below.

Source: gwt-maven-plugin — Running and debugging

-pl limits the build to the named module and -am ("also make") adds the modules it depends on, here bookshelf-shared, so the code server sees the shared sources. The code server prints, on the first start:

Source: gwt-maven-plugin — Running and debugging

The "Ignoring …​ bookshelf-shared:jar" line is information, not a problem: the plugin uses the sources classifier dependency and the reactor module’s source folder instead, so shared code changes are picked up immediately. The server listens on 127.0.0.1:9876 by default; the excerpt above comes from a run that changed the port to 9911 with <codeserverArgs> in the root POM (shown below) to avoid a clash with other processes. The code server is the long-running process: leave it open.

The official page and the archetype README write the module selector as -pl *-client -am. That form does not work on Maven 3.9.16:

Source: Apache Maven — Command line options (-pl, -am)

Use the explicit module name (-pl bookshelf-client), the groupId-less form -pl :bookshelf-client (also verified), or leave -pl out and let the reactor build everything; the archetype README says -pl and -am are "not strictly necessary", they only keep Maven from building the client when you work on the server and the other way around. The official samples' own README files use the explicit form (-pl mail-client -am).

In a second terminal, start Jetty with the env-dev profile. The prefix jetty resolves to the jetty-ee10-maven-plugin configured in the POM:

Source: Jetty — Maven Plugin

Start it after the code server has printed "ready". The code server creates launcherDir, and Jetty is configured to serve it; if it does not exist yet, Jetty stops with Bad resourceBases: [...]: Does not exist: file:///.../target/gwt/launcherDir/. The same happens right after a mvn clean, which deletes the folder. When Jetty is up, open http://localhost:8080 (add -Djetty.http.port with another number to change the port) and the application appears. The first load is slow because the code server compiles the module on the first request: in my run, "Compile completed" took 3.8 seconds.

The jetty plugin is configured with <scan>1</scan>, so Jetty reloads when the server classes or web.xml change. Server code changes need no restart of the code server, and client code changes need no restart of Jetty.

The loop is: edit a Java file in the client or the shared module, save, and reload the browser tab. Nothing is built in the background; the reload is what triggers the compile.

This was measured on the Bookshelf: a one-line change to a status message and a reload gave a recompile of five changed types in about 0.47 seconds, against 3.8 seconds for the first compile. The code server log for that reload:

Source: GWT — Super Dev Mode

Two things make this fast. The recompile is incremental, which is on by default in the code server and works on a single permutation: the browser tells the code server its user.agent binding (here safari), so only that permutation is compiled. A request with no binding gives Current binding properties are expanding to more than one permutation but incremental compilation requires that each compile operate on only one permutation. and nothing is compiled, which is what you see if you call /recompile/<module> with curl. And when nothing changed, the log says skipped compile because no input files have changed.

A compile error does not break the page. After saving a broken line (int broken = "text";) the reload gave this in the code server log, and the browser showed a "failed" message with a "Try Again" button and kept the previous version running:

Source: GWT — Compiling and Debugging: Super Dev Mode

Source maps are on by default since 2.12.0 (the log shows "Source Maps Enabled"), so the developer tools show the Java files themselves. In Chrome, open the developer tools, the Sources tab, press the Ctrl key (Cmd on macOS) together with P, type the file name, for instance App.java, and set a breakpoint in the Java source. The same page of the official getting-started guide shows the steps. Development Mode & Debugging covers breakpoints, logging and the other tools.

mvn package runs the GWT compiler. It writes the JavaScript into the client module and overlays it into the server war:

Source: GWT — Getting Started: Compile and run in production mode

On the Bookshelf this takes about 7 seconds in total, of which the GWT compile is 4 to 5 seconds, and ends with BUILD SUCCESS for the shared, client and server modules. The server war bookshelf-server/target/bookshelf-server-1.0-SNAPSHOT.war contains index.html, WEB-INF/web.xml, and the compiled application under bookshelf/: bookshelf.nocache.js, one *.cache.js file per permutation (two here: gecko1_8 and safari), compilation-mappings.txt, clear.cache.gif and the Clean theme’s clean.css. The war can be deployed to any Jakarta EE 9 or newer servlet container. To try it without installing one, run it through the Jetty plugin; the official samples use the same command:

Source: GWT repository — samples/showcase README

Requests for / and for /bookshelf/bookshelf.nocache.js returned 200 in my run. mvn package is also what a CI job runs, and mvn verify and mvn install additionally run the tests and make the modules available to other builds.

Save the files and reload the browser tab: the screen appears, the status shows The catalogue is empty., and an empty submit shows Both the title and the author are required.. I verified adding a book (1 book in the catalogue. and the entry in the list) and the Clear catalogue menu item, which empties the list and shows the empty message again.

Source: GWT Javadoc — MenuBar

The sample uses plain text everywhere. A few of the widgets' methods interpret their argument as HTML: the Button(String) constructor takes HTML (it is annotated as a SafeHtml-sensitive parameter), HTML.setHTML(String) and the addItem overload with an asHTML flag set to true do as well. Never pass user data to them concatenated; use setText, or build the markup with SafeHtmlBuilder and pass a SafeHtml. The archetype’s own sample does that for the server’s reply. Authorisation never belongs in client code: anything the browser does can be replayed by a script, so the server module checks who is allowed to do what. SafeHtml & XSS and XSRF, RPC & Server Security cover cross-site scripting, XSRF and the server-side checks.

Source: GWT — Using SafeHtml: Prefer Plain Text