Skip to content
Inertia

Introduction

Inertia for Kona lets your JVM app return a page object — a component name plus props — that a JavaScript client hydrates. The first visit is a normal HTML document. Later navigations send the X-Inertia header and receive JSON instead of a full page reload.

You keep routing, controllers, auth, and validation on the server. The browser mounts a client framework (Vue, React, Svelte, or anything that can read the page object) and swaps pages when Inertia navigates.

What ships in this package

Section titled “What ships in this package”
Piece Role
Inertia facade Java-callable statics: render, share, version, location
InertiaManager Builds HTML shells and JSON page responses
HandleInertiaRequests Middleware: per-request shared props, version checks, response headers
InertiaServiceProvider Binds manager + Vite AssetManifest
org.konaframework.inertia.assets.Vite Thin facade over Crema’s Vite resolver

Artifact: org.konaframework:kona-inertia from konaframework/kona-inertia.

When to use it

Section titled “When to use it”

Use Inertia when you want a modern SPA UX without writing a separate JSON API for every screen. Controllers return page props; the client renders named components.

If you prefer reactive server components without a JS SPA stack, see Brew instead. For classic HTML templates, use Crema.

Protocol at a glance

Section titled “Protocol at a glance”
  1. First visit (no X-Inertia) → HTML shell with data-page='…json…' on #app.
  2. Inertia visit (X-Inertia: true) → JSON { component, props, url, version } plus X-Inertia / X-Inertia-Version.
  3. Version mismatch → 409 so the client can hard-reload assets.
  4. External redirect via Inertia.location → 409 + X-Inertia-Location for Inertia clients; ordinary browsers get 302.

Install in one command

Section titled “Install in one command”
Terminal window
./grind install inertia
# interactive frontend: Vue / React / Svelte
# or greenfield:
kona new my-app --kit=inertia

That path covers the Maven artifact and a Vite client scaffold. Walkthrough: Installation.

Client protocol and adapters: inertiajs.com.

Next steps

Section titled “Next steps”