Forge Files and State

Quarkus Forge uses two storage scopes with different purposes.

1) Machine-Local App Data (~/.quarkus-forge/)

This directory stores user-specific runtime data:

  • catalog-snapshot.json: last known extension catalog snapshot (offline/stale fallback).

  • preferences.json: saved user preferences (last platform, build tool, java version, etc.).

  • favorites.json: extension favorites used by the TUI and the favorites preset.

  • recipes/: shareable Forgefile templates for cross-project reuse.

These files are machine-local and should not be committed to project repositories.

2) The Forgefile

A Forgefile is a single JSON file that serves as both a project template and a deterministic lock:

{
  "groupId": "com.acme",
  "artifactId": "my-service",
  "version": "1.0.0-SNAPSHOT",
  "buildTool": "maven",
  "javaVersion": "25",
  "extensions": ["io.quarkus:quarkus-rest"],
  "presets": ["web"],
  "locked": {
    "platformStream": "io.quarkus.platform:3.31",
    "buildTool": "maven",
    "javaVersion": "25",
    "extensions": ["io.quarkus:quarkus-rest", "io.quarkus:quarkus-arc"],
    "presets": ["web"]
  }
}

  • Top-level fields: human intent — what you want to generate.

  • locked section (optional): exact resolved values for deterministic builds.

When to use the locked section

  • CI pipelines: ensure identical project generation across environments.

  • Team sharing: lock exact versions so everyone generates the same project.

  • Drift detection: --lock-check verifies no unintended changes.

Recommended placement

  • Reusable templates: store under ~/.quarkus-forge/recipes/.

  • Project-specific Forgefile for strict reproducibility: keep in the project repository root.

CLI Resolution Rules

generate --from behavior:

  • If the provided path exists locally, it is used directly.

  • If local path is missing, Forge resolves it from ~/.quarkus-forge/recipes/.

generate --save-as behavior:

  • If a full/relative path is provided (for example ./Forgefile), Forge writes there.

  • If a simple name is provided (for example starter.json), Forge writes to ~/.quarkus-forge/recipes/starter.json.

TUI Export

After generating a project in the TUI, the "Export Forgefile" post-generation action writes a complete Forgefile (with locked section) to the generated project directory.

CI Pipeline Integration

GitHub Actions

- name: Generate Quarkus project
  run: |
    java -jar quarkus-forge-headless.jar generate \
      --from Forgefile \
      --lock-check \
      --output-dir .

Use --lock-check to detect drift between the Forgefile and the locked section, failing the build if any difference is found.

Lock workflow

# 1. Developer configures project
java -jar quarkus-forge-headless.jar generate \
  --group-id com.acme --artifact-id my-service \
  --build-tool maven --java-version 25 \
  --extension io.quarkus:quarkus-rest \
  --save-as Forgefile --lock

# 2. CI verifies no drift
java -jar quarkus-forge-headless.jar generate \
  --from Forgefile --lock-check --dry-run

Offline / air-gapped environments

Forge falls back to ~/.quarkus-forge/catalog-snapshot.json when the API is unreachable. Pre-populate the snapshot on a connected build agent and copy it to the air-gapped environment.