Create a project with Maven Archetypes

The JoinedWorkz Maven Archetypes create independent, runnable multi-module projects without requiring a JoinedWorkz source checkout. Use them when you want to start a new Spring Boot application or a Spring Boot application with an experimental Quasar frontend.

If you first want to understand the model, Maven plugin and generated output in isolation, use the transparent Base Quickstart. To add JoinedWorkz to an existing project or design a custom module layout, use the manual Maven setup.

Release compatibility

Archetype release 1.0.0 targets JoinedWorkz 1.3.81, Java 21 and Maven 3.9+. Archetype versions and JoinedWorkz versions are independent; use the compatibility table on this page instead of assuming that their version numbers match.

1. Choose an Archetype

Spring Boot

joinedworkz-spring-boot-archetype is the stable starter. It creates a model module, generated backend module and manual Spring Boot application shell.

Spring Boot with Quasar

joinedworkz-fullstack-quasar-archetype adds a Quasar frontend and its manual application shell. The Spring Boot backend is stable; the Quasar frontend is experimental.

Both Archetypes are published under the Maven group org.joinedworkz.archetypes. Their source, descriptors and starter templates are maintained in the joinedworkz-archetypes repository.

2. Prerequisites

Install:

• Java 21;
• Maven 3.9 or newer for the initial project generation; and
• Docker or another reachable PostgreSQL installation only when you select postgresql.

Every generated project includes a Maven Wrapper pinned to Maven 3.9.16. The H2 variant runs with a persistent project-local database and does not require Docker.

The full-stack Maven build installs its pinned Node.js and npm versions below the frontend module, so a global Node.js installation is not required for ./mvnw clean verify. Interactive frontend development uses Node.js 22.22.2 and npm 11.6.0.

Do not build a generated reactor with Maven's parallel -T option. Model generation writes into downstream sibling modules, so the reactor order must remain sequential.

3. Generate a Spring Boot project

The following command creates a runnable application backed by H2:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.1:generate \
  -DarchetypeGroupId=org.joinedworkz.archetypes \
  -DarchetypeArtifactId=joinedworkz-spring-boot-archetype \
  -DarchetypeVersion=1.0.0 \
  -DgroupId=com.example \
  -DartifactId=catalog-service \
  -Dversion=1.0.0 \
  -Dpackage=com.example.catalog \
  -DapplicationName=CatalogService \
  -DapplicationTitle="Catalog Service" \
  -Ddatabase=h2

Build and start the generated project:

cd catalog-service
./mvnw clean verify
./mvnw -pl backend-spring-app -am spring-boot:run

The starter API is available below http://localhost:8080/api/v1/items and Swagger UI at http://localhost:8080/swagger-ui.html.

The generated reactor contains:

model
backend-spring-generated
backend-spring-app

4. Generate a Spring Boot and Quasar project

The full-stack Archetype adds an experimental model-generated Quasar frontend. This example embeds the production frontend build in the Spring Boot application:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.1:generate \
  -DarchetypeGroupId=org.joinedworkz.archetypes \
  -DarchetypeArtifactId=joinedworkz-fullstack-quasar-archetype \
  -DarchetypeVersion=1.0.0 \
  -DgroupId=com.example \
  -DartifactId=catalog-application \
  -Dversion=1.0.0 \
  -Dpackage=com.example.catalog \
  -DapplicationName=CatalogApplication \
  -DapplicationTitle="Catalog Application" \
  -Ddatabase=h2 \
  -DfrontendDelivery=spring-boot

Build and start the backend:

cd catalog-application
./mvnw clean verify
./mvnw -pl backend-spring-app -am spring-boot:run

Create one item through the generated backend API:

curl -X POST http://127.0.0.1:8080/api/items \
  -H 'Content-Type: application/json' \
  -d '{"name":"First item","description":"Created through the generated API"}'

Open http://127.0.0.1:8080/items for the embedded production frontend. The API is available below http://127.0.0.1:8080/api/items, and Swagger UI is at http://127.0.0.1:8080/swagger-ui.html.

For interactive frontend development, leave the backend running and start the Quasar development server in a second terminal:

cd frontend-quasar
npm ci
npm run dev

Then open http://127.0.0.1:9000/items. The development server proxies /api to the backend on port 8080.

The generated reactor contains:

model
backend-spring-generated
frontend-quasar
backend-spring-app

5. Parameters

Provide the standard Maven coordinates and Java package explicitly for a reproducible non-interactive command:

Parameter	Contract
groupId	Maven group of the generated project
artifactId	Maven artifact and generated project-directory name
version	Initial version of the generated project
package	Base Java package for manual application source
applicationName	Application identifier; starts with an uppercase letter and then uses only letters or digits; default Application
applicationTitle	Human-readable title; quote values containing spaces; default JoinedWorkz Application
database	h2 or postgresql; default h2
frontendDelivery	Full-stack only: standalone or spring-boot; default standalone

With database=h2, runtime data is stored below the generated project's .data directory and tests use a separate in-memory database. With database=postgresql, use the included compose.yaml, a local PostgreSQL server or another reachable instance.

With frontendDelivery=spring-boot, the production SPA is packaged into the backend application. With frontendDelivery=standalone, Maven leaves the production files below frontend-quasar/dist/spa; deploy that directory with a static server that supports history-mode fallback and routes /api to the backend.

6. Ownership after generation

The Archetype creates manual application shells and authoritative CMN models. Replaceable Java, OpenAPI and Quasar output is intentionally absent from the template and appears during the first build. Change the CMN source and regenerate instead of editing those generated files.

The initial Flyway migration and matching schema snapshot are different: they are persistent database history and must be reviewed and retained. The generated project README identifies the exact manual, replaceable and persistent paths for the selected variant. See Generated output and ownership before restructuring the generated modules.

The starters use genesis-spring as ready-to-run Glue Code for examples, prototypes and first experiments. Production projects can provide compatible project-owned implementations, route the generated imports with package overrides and remove the Genesis runtime dependency.

7. Troubleshooting

• Use the explicit plugin and Archetype coordinates shown above. Do not add -DarchetypeCatalog=local; that option is for locally installed Archetypes, not the public release.
• Shortly after publication, Maven can report that an Archetype is not yet in a catalog and then fall back to Maven Central. This is informational when the download and generation continue.
• If Maven cached an earlier failed lookup, rerun the same command with -U before changing any coordinates.
• Parameter values are case-sensitive. Use h2 or postgresql and, for the full-stack Archetype, standalone or spring-boot.
• The first full-stack build downloads the pinned frontend toolchain and can therefore take longer than later builds.

See the symptom-first Troubleshooting reference for resolution and parameter diagnostics.