---
title: The Cratis Java Application template
editUrl: https://github.com/Cratis/Templates/edit/main/Documentation/cratis-java/index.mdx
description: Run the Cratis Java template with Spring Boot, Arc commands and queries, Chronicle events and a React frontend calling generated TypeScript proxies.
lastUpdated: 2026-11-05T00:00:00.000Z
---


Build a Spring Boot application in Java, register a named item, and see it in the React frontend. Cratis Arc exposes the commands and queries over HTTP; Cratis Chronicle stores the events behind the listing. The `cratis` template supplies the backend, frontend, and local infrastructure. Your application code is Java, while the build still uses Kotlin and KSP for Arc's generated Kotlin adapters.

## Before you begin

- **JDK 17.** The build uses a Gradle Java toolchain pinned to 17 and does not download one, so a JDK 17 must be installed where Gradle can find it, for example through `JAVA_HOME`. A newer JDK on its own fails with `Cannot find a Java installation on your machine … matching: {languageVersion=17 …}`.
- **Docker** with the Compose plugin, for the local Chronicle kernel.
- **Node.js `^20.19.0` or `>=22.12.0`** and yarn, pnpm, or npm for the frontend.

The .NET SDK is needed only if you scaffold with `dotnet new`; the generated project builds with the bundled Gradle wrapper.

The run steps below use the default MongoDB storage and yarn package manager. Choose different scaffold options only if you need them; the reference is under [Options](#options).

Choose one scaffolding tool. For `dotnet new`, run:

```bash
dotnet new install Cratis.Templates
dotnet new cratis --language Java -n MyStore
```

Alternatively, install the [Cratis CLI](/cli/) and use its scaffold command instead:

```bash
cratis new cratis --language java -n MyStore -o MyStore --allow-scripts yes
```

`Cratis.Templates` includes the Java template; `Cratis.Templates.Java` publishes the same template on its own. There is no `cratis-java` short name.

## Run it

Before starting the backend, keep it local: Spring Boot listens on every interface by default. Set `server.address=127.0.0.1` in `application.properties`. The generated `docker-compose.yml` already binds its published ports to `127.0.0.1`.

Start Chronicle in Docker, then build the backend before starting the frontend. The frontend's `Api` imports point to `build/generated/arc-proxies/`, the Arc Gradle plugin's configured output directory, so the backend build comes first.

```bash
cd MyStore
docker compose up -d        # Chronicle kernel and Aspire dashboard
./gradlew build             # compiles and generates the TypeScript proxies
yarn install                # skip if the scaffold already installed dependencies
./gradlew bootRun           # backend on http://localhost:8080
```

In a second terminal opened in `MyStore`, start the frontend:

```bash
yarn dev
```

Vite serves the frontend on `http://localhost:9000`, opens it in your browser, and forwards `/api` and `/.cratis` to the backend. Open **Demo**, choose **Register**, enter a name, and submit it. The expected result is that name appearing in the list. To follow the same registration without the frontend, use the command and query requests under [The sample slices teach the conventions](#the-sample-slices-teach-the-conventions).

When the helper exits, whether you press Ctrl+C or a step fails, it runs `docker compose down`. This removes the containers and, with the default MongoDB storage, every event and read model. Use the manual steps with `docker compose stop` when you want to keep data between runs.

Instead of the manual steps, use `./run.sh` to start Chronicle, build the backend, and launch the frontend and backend from one terminal.

The helper tries yarn and falls back to npm. `./run.sh --no-frontend` starts only Chronicle and the backend.

The project includes a `.yarnrc.yml` that sets `nodeLinker: node-modules`, so Yarn 2 and later install into `node_modules` instead of Plug'n'Play, which the TypeScript 7 compiler cannot resolve. npm, pnpm, and Yarn 1 ignore the file.

## What you get

```text
MyStore/
├── build.gradle.kts           — Gradle build with the Arc plugin
├── settings.gradle.kts        — plugin and dependency repositories
├── gradlew, gradle/wrapper/   — Gradle wrapper (9.1.0)
├── run.sh                     — starts Chronicle, the backend, and the frontend together
├── docker-compose.yml         — Chronicle dev container + Aspire dashboard
├── package.json               — frontend tooling (Vite, React, Cratis Components)
├── .frontend/                 — Vite and TypeScript configuration
├── App.tsx, Home.tsx          — frontend application shell
├── SomeModule/                — the sample frontend slices
└── src/main/
    ├── java/com/example/
    │   ├── MyStoreApplication.java     — Spring Boot entry point
    │   ├── ChronicleConfiguration.java — Chronicle options and artifact registration
    │   └── somemodule/                 — the sample backend vertical slices
    ├── kotlin/com/example/PackageMarker.kt — keeps the package visible to KSP; leave it in place
    └── resources/application.properties   — event store name and route settings
```

## The sample slices teach the conventions

Start with `Register`: its `handle()` returns a `Registered` event containing the name, wrapped in a completed `CompletionStage`. The command does not build the listing itself. From `registration/Register.java`; the event and reactor have their own files in the same folder:

```java
@Command
@AllowAnonymous
public record Register(@CommandKey SomeId id, SomeName name) {
    public CompletionStage<Registered> handle() {
        return CompletableFuture.completedFuture(new Registered(name()));
    }
}
```

`SomeId` wraps the command's string identity. Its two `ConceptAs<String>` contracts expose that value to Arc and Chronicle. The event carries the name; the reducer takes the listing's `id` from the event context, so it refers to the same event source as the command key.

To put the registered name on screen, `ListingReducer` builds a `Listing` from the `Registered` event and its event-source identity. The query reads those stored listings through the `Chronicle` facade. Although it returns a `CompletionStage`, it calls the blocking read facade before wrapping the result. From `listing/Listing.java`:

```java
@io.cratis.arc.artifacts.ReadModel
@io.cratis.chronicle.readModels.ReadModel
@AllowAnonymous
public record Listing(String id, SomeName name) {
    @Path("/api/listings")
    public static CompletionStage<List<Listing>> all(@FromServices Chronicle chronicle) {
        return CompletableFuture.completedFuture(chronicle.readModels(Listing.class));
    }
}
```

The scaffold's `ChronicleConfiguration.java` supplies an explicit list of the sample event, read model, reducer, and reactor. With the backend running, use the requests below to submit the command and read the listing without the React frontend.

```bash
curl -sS -X POST http://localhost:8080/api/register \
    -H 'Content-Type: application/json' \
    -d '{"id":"'$(uuidgen)'","name":"Cratis"}'

curl -sS -X QUERY http://localhost:8080/api/listings \
    -H 'Content-Type: application/json' \
    -d '{"arguments":{}}'
```

The first call returns `"isSuccess":true`. The second returns the listing in `data`, for example `[{"id":"…","name":"Cratis"}]`. `GET /api/listings` returns the same result.

## Options

| Option | Values | Default |
| --- | --- | --- |
| `--Database` | `MongoDB`, `PostgreSQL`, `MsSql`, `SQLite` | `MongoDB` |
| `--packageManager` | `yarn`, `pnpm`, `npm`, `none` | `yarn` |
| `--SkipAiUpdateInstructions` | `true`, `false` | `false` |

The application code is the same for every database, because the Chronicle kernel persists the read models. `--Database` changes how the Chronicle container in `docker-compose.yml` stores its data (embedded MongoDB, a PostgreSQL or SQL Server container, or an SQLite file on a named volume) and switches the default read-model sink in `ChronicleConfiguration.java` between MongoDB and SQL:

```bash
dotnet new cratis --language Java -n MyStore --Database PostgreSQL
```

## Versions

The Arc Gradle plugin (`io.cratis.arc`) and `io.cratis:cratis`, the one dependency that bundles Arc, its Spring Boot wiring, and the Chronicle client, are requested as `latest.release`. Gradle resolves both requests when it builds; `latest.release` does not pin a reproducible pair in this file. Gradle caches a dynamic version for up to 24 hours by default; `./gradlew build --refresh-dependencies` picks up a newer release immediately.

For a reproducible or production build, replace `latest.release` with the exact version you tested, keeping the plugin and the `io.cratis:cratis` dependency on the same version, or enable Gradle dependency locking.

The rest of the build is pinned:

| Dependency | Version | Where |
| --- | --- | --- |
| Kotlin | 2.4.20 | `build.gradle.kts` |
| KSP | 2.3.12 | `build.gradle.kts` |
| Spring Boot | 4.1.1 | `build.gradle.kts` |
| Java toolchain | 17 | `build.gradle.kts` |
| Gradle | 9.1.0 | `gradle/wrapper/gradle-wrapper.properties` |

`build.gradle.kts` also pins `kotlinx-coroutines-core` to the version the Cratis libraries are compiled against, because Spring Boot's dependency management would otherwise select an older one that fails at startup.

## Troubleshooting

- **`Cannot find a Java installation … languageVersion=17`.** Install a JDK 17 and point `JAVA_HOME` at it.
- **`Cannot find module` during the frontend build.** Yarn 2 or later installed with Plug'n'Play because `.yarnrc.yml` is missing (projects scaffolded from earlier template versions do not have one). Add one containing `nodeLinker: node-modules` and run `yarn install` again.
- **Port 8080 or 35000 is already in use.** Stop the other process, or move the service. For the backend, set `server.port` in `application.properties` and update the two `http://localhost:8080` proxy targets in `.frontend/vite.config.ts`. For Chronicle, change the host side of the mapping in `docker-compose.yml` and point `cratis.chronicle.connection-string` at the new port.
## AI assistance

If you want coding-agent guidance, the scaffolded project includes a `.cratis/ai.json` selecting the `cratis/application/java` profile with the Java and TypeScript languages. After `dotnet new`, make sure the [Cratis CLI](/cli/) is installed, then run:

```bash
cratis ai update
```

`cratis new` runs this step for you. See the [CLI AI documentation](/cli/ai/) for the full command reference.
