docs: add a hotswap guidelines chapter on regenerating frontend files - #25806

Test Results

 1 454 files   -  1   1 538 suites   - 1   1h 31m 29s ⏱️ + 1m 38s
11 926 tests  - 13  11 858 ✅  - 13  68 💤 ±0  0 ❌ ±0 
12 244 runs   - 13  12 176 ✅  - 13  68 💤 ±0  0 ❌ ±0 

Results for commit d644415. ± Comparison against base commit 487fb8c.

♻️ This comment has been updated with latest results.

@claude review if these are actually followed in the project

Claude finished @Artur-'s task in 2m 20s —— View job

Review: are these practices actually followed in the project?

I checked every concrete claim in guidelines/hotswap.md against the current code. Almost everything is accurate and matches the implementation. I found one description that doesn't quite match the code, plus a couple of minor simplifications worth noting.

• Read the new chapter and extract the checkable claims
• Verify Flow-task claims
• Verify browser-notification claims
• Verify Hilla endpoint claims
• Verify dev-loop restart claim
• Verify testing claim
• Post findings

✅ Verified accurate

The Hilla-side symbols the doc names (com.vaadin.hilla.Hotswapper, EndpointCodeGenerator.update(String...)) live in the separate hilla repo, so I couldn't verify them here — but the Flow-side SPI they hang off of is exactly as described.

⚠️ One description that doesn't match the code

RouteRegistryHotswapper gating (hotswap.md:86-88) — the doc says:

RouteRegistryHotswapper collects the registry's layouts before and after applying the class changes and only calls writeLayouts when that set differs.

That's not what the code does. It collects layouts before and after into the same HashSet (a union, not a diff), then gates on whether any changed class is a member of that union:

Set<Class<?>> layouts = new HashSet<>(((AbstractRouteRegistry) appRegistry).getLayouts());
RouteUtil.updateRouteRegistry(appRegistry, addedClasses, modifiedClasses, removedClasses);
layouts.addAll(((AbstractRouteRegistry) appRegistry).getLayouts());

if (configuration.isReactEnabled()
        && Stream.of(addedClasses, modifiedClasses, removedClasses)
                .flatMap(Set::stream).anyMatch(layouts::contains)) {
    ... writeLayouts(...);
}

(RouteRegistryHotswapper.java:79-100)

So the real gate is "a changed/added/removed class is, or just stopped being, a @Layout" (plus a React-enabled check the doc omits) — never a before-vs-after set comparison. The union of before+after exists precisely so a class that lost its @Layout annotation still matches. The doc's "only when that set differs" phrasing describes a diff that isn't there and would give a reader the wrong mental model when writing their own gate. Worth rewording to something like "only when one of the changed classes is (or was) a layout".

Fix this →

Minor notes (not errors)

• hotswap.md:74-75 says AbstractFileGeneratorFallibleCommand.writeIfChanged "delegates to FileIOUtils.writeIfChanged". There's an intermediate hop through GeneratedFilesSupport.writeIfChanged (which also does the track() bookkeeping) before reaching FileIOUtils. The Hilla section (:144-146) correctly attributes writeIfChanged to GeneratedFilesSupport, so the two passages are slightly inconsistent about which class "owns" it. Harmless, but a one-line tweak would make them agree.
• The example snippet at :42-47 uses appRegistry.getLayouts() while the real call casts (((AbstractRouteRegistry) appRegistry).getLayouts()). Fine as a doc simplification.

Bottom line: the guidelines faithfully reflect the implementation. The only substantive correction is the RouteRegistryHotswapper gating description — it's a diff-vs-union/membership mismatch that I'd recommend rewording before merge.
· branch docs/hotswap-generated-frontend-files

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud