| name | mateu-scaffold |
| description | Scaffold a new Mateu project or module and wire the Maven build correctly — the two-step annotation processing (indexer + framework AP), the renderer dependency, and the Spring Boot main class. Use when starting a new Mateu app, adding a framework-agnostic @UI module, or fixing "my @UI class compiles but no controller is generated / the route 404s / nothing renders". Triggers on new Mateu project, pom.xml, annotationProcessorPaths, annotation-processor-indexer, annotation-processor-mvc, mvc-core, vaadin-lit. |
Scaffolding a Mateu project
The code (@UI classes) is the easy part — the fiddly part is the build wiring.
Mateu generates its controllers at compile time via annotation processors, so the
pom.xml must be set up exactly right or you get a clean compile that produces no
UI at all.
Pick the layout
| Situation | Layout | Poms |
|---|
One app, @UI classes live in the app itself | single-module app | app-pom.md |
@UI classes in a reusable, framework-agnostic module consumed by one or more apps | UI module + app | ui-module-pom.md + app-pom.md |
Choose the UI-module layout when the screens should be publishable/shareable with no
Spring (or Quarkus/…) dependency, or when several apps/services reuse them (see the
mateu-federation skill).
The golden rule (why builds silently render nothing)
Annotation processors only see the sources of the module being compiled. So:
- A framework-agnostic
@UI module must run the indexer AP
(io.mateu:annotation-processor-indexer) — it writes META-INF/mateu/ui-registrations
into the jar so downstream apps can discover its screens without the sources.
- The app module must put, on
annotationProcessorPaths, both the framework AP
(io.mateu:annotation-processor-mvc) and every @UI module it consumes — the
framework AP reads each module's index off the classpath and generates the controllers
in the app.
If a @UI module is a regular <dependency> of the app but not also listed under
<annotationProcessorPaths>, its screens are never generated. This is the #1 mistake.
Runtime + renderer dependencies (app module)
The app needs the runtime (io.mateu:mvc-core) and one renderer jar so the UI is served:
<dependency><groupId>io.mateu</groupId><artifactId>mvc-core</artifactId><version>${mateu.version}</version></dependency>
<dependency><groupId>io.mateu</groupId><artifactId>vaadin-lit</artifactId><version>${mateu.version}</version></dependency>
mvc-core = the Spring MVC runtime (the /mateu/v3/sync endpoint, SpaRedirectFilter).vaadin-lit = the default renderer, served as static resources by Spring Boot (swap for
sapui5-lit, redhat-lit, redwood-lit, slds-lit). See the run step below and the
standalone/CDN options in doc/.../mateu-about/standalone-desktop.md.
Other stacks replace the mvc pair: webflux, quarkus, micronaut, helidon-mp
(each has its own *-core + annotation-processor-*).
Main class
@SpringBootApplication(scanBasePackages = {"io.mateu", "com.yourco.yourapp"})
public class Application {
public static void main(String[] args) { SpringApplication.run(Application.class, args); }
}
scanBasePackages must include io.mateu so the framework's beans/controllers are
picked up, plus your own package(s).
Versions
Use a mateu.version property. When building against a local mvn install of this repo
it is 0.0.1-MATEU; for a published build use the latest release from GitHub
releases / Maven Central. Lombok and jakarta.validation-api are the only extra
compile-time helpers the samples use. Java 17+ (samples use 21).
After scaffolding — verify it actually generated
Don't trust a green build. Confirm the controllers exist and the route responds:
verify.md.
Related skills
- Build, run and screenshot the result → mateu-run.
- Compose several modules/services into one UI → mateu-federation.
- Write the actual
@UI screens → mateu.
