Vaadin dev loop
vaadin-dev is a CLI over a daemon that owns the application's process: it compiles edits
in the background, hot-swaps or restarts, and answers authoritatively "what is the state of my
last change?" apply proves the bytes are live; only the browser proves the UI renders what
you intended.
The vaadin-dev script belongs to a target application — the module holding the Vaadin
app's pom.xml, its Maven wrapper and its .vaadin/ — and by default acts on that one. Run it
from there as .vaadin/vaadin-dev, or from any directory with --app <dir> (or
VAADIN_DEV_APP=<dir>), which is also how a single copy of the script drives another Vaadin
application in the same reactor.
Requires Vaadin 25.3 or newer
The dev loop ships with Vaadin 25.3. Establish the target application's Vaadin version once,
before the first command — vaadin.version in its pom.xml, or
./mvnw -q help:evaluate -Dexpression=vaadin.version -DforceStdout when the pom inherits it
from a parent. On anything older nothing here applies: there is no com.vaadin:vaadin-dev to
resolve a daemon from, so run the application the project's normal way and say that the loop is
unavailable, rather than invoking vaadin-dev and reporting its failure. When a command names
another application with --app, the version that counts is that application's.
The cycle
.vaadin/vaadin-dev statusfirst — it costs milliseconds (no JVM per command) and everything after depends on the answer.If it says
stopped,.vaadin/vaadin-dev start— it blocks for ~30 s on a cold start, so run it in the background and read the code while it boots.Open the app in the browser now, before the first
apply, and keep that page open, unless the change ahead has no visual surface at all — step 5 defines which those are. A CSS or theme push has somewhere to land only if a page is already connected: with none,applysays the resource was copied to the classpath and nothing about a push, which is honest but is not the answer you came for. Opening the page afterwards serves the new file from disk, so the change shows up — but that apply's verdict cannot be recovered.Edit Java, CSS and/or frontend files. Batch the edits —
applyfinds the change-set itself by scanning the sources of every module in the loop. Run it once after a batch, not per file..vaadin/vaadin-dev apply— the exit code is the verdict:0live,1failed,4superseded.Verify what actually changed, and only then report it as working. A change with a visual surface — a view, component, layout, theme, stylesheet — is verified in the page opened in step 2; nothing else proves the UI renders what you intended. A change with none — a service, a repository, a formatter, a config value — is answered in full by
apply's verdict and the project's own tests, so opening a browser to look at nothing buys no evidence and costs the run a browser launch.Use whatever browser automation you already have — a Playwright or browser MCP server, a built-in browser tool, or the browser tests the project itself runs; one is preferred over another only by convenience, and none of them is required. Snapshot or evaluate the open page for the assertion, and read the browser console after each change (a
/favicon.ico404 is normal noise). The first snapshot after navigating is usually empty — Vaadin renders client-side, so wait for a known element or re-snapshot before asserting. With no browser automation at all, extend a*BrowserTestor*ITclass the project already has, using the element API it already depends on, and say that is where you verified.Never build a browser harness for one change — it costs more than the change, and a loop over ten viewport widths is one. Where the project ships a checker of its own, it is the grader: run it and read its report instead of re-measuring by hand. Verifying in the browser in reference.md says what a run with no browser at all can and cannot claim.
Verification ends the cycle. A change apply reports live and step 5 has verified is
finished; where the project has tests or checks that cover it, their passing is that
verification. Go back to step 3 for work that is left, or for evidence that contradicts you —
never to improve on a result that already met the bar.
Commands
.vaadin/vaadin-dev status [--json] app up? registered? dev server? last transaction
.vaadin/vaadin-dev start launch the app in dev mode; blocks until serving or failed
.vaadin/vaadin-dev apply [--json] make the edits on disk live; blocks until Stable or Failed
.vaadin/vaadin-dev restart stop + start — required after configuration changes
.vaadin/vaadin-dev stop | shutdown stop the app / stop the daemon too
vaadin-dev is a Bash script, and the install goal marks it executable, so run it from a
shell as written above. If your shell will not execute it — Windows checkouts carry no
executable bit — run bash .vaadin/vaadin-dev … instead, or from cmd/PowerShell use
.\.vaadin\vaadin-dev.cmd. Every command, option and exit code is identical whichever you
use.
Never start the application through Maven (spring-boot:run, jetty:run, an IDE run
configuration): the daemon owns the app, and a second process fights it for the HTTP port. The
daemon auto-spawns on first use and survives between commands, so every command — from any
shell, agent or IDE — answers for the same running app.
That holds for a WAR project too, and there the daemon runs the project's own jetty:run
for you — a WAR has no main class, and its servlet container is a build plugin rather than a
dependency, so the build is the only thing that knows how to start it. Once started, status
names the runtime it chose (runtime=jetty-ee10). Nothing in the pom needs changing: the
daemon turns the plugin's own rescanner off for its run, because two things redeploying the app
on separate schedules is what the loop exists to prevent, and it says so in the app log.
And do not reach for Maven to check an edit. mvn compile and mvn test boot a fresh JVM
and a fresh Spring context to answer what apply answers against the app already running, and
they answer a narrower question: that the code compiles, not that the change is live in the
page. Compile errors come out of apply with the same diagnostics, against the same sources.
Run the project's own test suite once, at the end, over the change as a whole — never as the
per-edit feedback loop.
What is in the loop
The daemon serves one application. When that application is a module of a Maven reactor,
every reactor module it depends on is in the loop too: apply scans src/main/java and
src/main/resources of each, compiles them, and hot-reloads or restarts exactly as it does for
the application's own code — so an edit in a sibling library module reaches the running page
without a rebuild.
The frontend folder belongs to the application alone — src/main/frontend, or frontend/
in an older project, or whatever the build recorded. apply scans it too, and what happens to
an edit there depends on the mode: in Vite mode Vite already applied it on save, and in
dev-bundle mode only a theme stylesheet can be pushed while everything else needs the bundle
rebuilt, which is why those edits restart the app. A sibling library contributes frontend
assets through its src/main/resources/META-INF/frontend, which is already the resource leg.
status names the modules in the loop. A module it does not name is one the application does
not depend on, and edits there are invisible to apply.
A reactor can hold more than one Vaadin application, and each gets its own daemon, its own
.vaadin/ handshake and its own target/devloop/ — so --app picks which one a command acts
on: .vaadin/vaadin-dev --app ../admin apply. Whenever the target is not the script's own
application, every command prints the application it answered for on stderr. Check that line
before trusting the answer.
.vaadin/vaadin-dev this CLI (committed); .vaadin/ also holds
daemon.properties, which is per-run state
src/main/java/ views + services (pure Java, no HTML/JS)
src/main/resources/META-INF/resources/ the app's CSS and icons
src/main/resources/application.properties config — needs restart
src/main/frontend/themes/<theme>/ theme CSS — pushed in place, no reload
src/main/frontend/ views, components, styles — a bundled edit
restarts the app in dev-bundle mode
src/main/frontend/generated/ generated by the build — never edit
target/devloop/app.log, daemon.log logs, under the target application
Reading the outcome, in one line each
| Output | Meaning |
|---|---|
hmr: … pushed 1 stylesheet(s) in place |
CSS is live in the open page, no reload |
hmr: … no browser connected |
the new CSS is on the classpath, but no page was open to push it into — open one and re-apply rather than reporting the change live |
hmr: N theme file(s) pushed in place |
theme CSS is live in the open page, no reload |
hmr: N frontend file(s), applied by Vite (dev server up:…) |
Vite mode: the edit went live when you saved it |
frontend → Failed with dev server: [vite] … |
Vite mode: Vite refused to compile the edit — exit 1. Fix the file it names and re-apply; a restart cannot compile it either |
hot-reload: redefineClasses(1); onHotswap completed=true |
Java hot-swapped, UI refreshed |
an hmr: line and a hot-reload: line |
a mixed change-set; both halves are live, and hmr: answers for the stylesheet |
→ live, but no Vaadin component was redefined |
bytes are live; interact with the view or reload to see it. Do not re-apply |
compiling → runtime → restarting → Stable |
the app restarted — reload the page |
restart: classpath changed (...) |
a pom edit moved the app's classpath |
restart: frontend changed (dev bundle rebuild) |
dev-bundle mode: only a Vite build folds a frontend file in, and the restart runs it — slow, and the page needs a reload |
restart: frontend imports changed (MyView) |
a @JsModule/@JavaScript/@CssImport/@NpmPackage/@Theme was added, changed or removed; those are read at startup, so the class redefining is not enough |
no changes (… pom.xml changed; nothing to recompile or restart) |
a positive answer, not a shrug |
compiling → Failed + diagnostics |
fix and re-apply; the app keeps its last good bytes |
app log: N error(s) since the change |
not a green result — the change is live and the app threw |
Stable with an app log: line under it is a failure to investigate, not a success.
The app serves on http://localhost:8080 unless server.port says otherwise. Navigate once,
in step 2, and keep the page open across applies — CSS pushes and Java hot-swaps land in an
already-open page, and re-navigating hides what you are testing.
Full reference
Read reference.md when you need it: the complete apply output vocabulary,
which kind of edit needs a page reload, pom/classpath semantics, the --json schema, the
browser assertion patterns, environment variables, and what to do when the loop goes wrong.