litestar-inertia

Stars13

Forks0

UpdatedJuly 23, 2026 at 16:30

Auto-activate for litestar_vite.inertia, InertiaConfig, component=, @inertia, @inertiajs/*, createInertiaApp, useForm, usePage, Link, router, or pages/. Not for HTMX.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

litestar-org

litestar-org/litestar-skills

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

3 files

SKILL.md

readonly

Litestar + Inertia.js Integration

litestar-inertia is the four-library story:

Layer	Library	Role
Client SPA	`@inertiajs/react` / `@inertiajs/vue3` / `@inertiajs/svelte`	Page resolution, forms, navigation, shared data access; generated templates target Inertia v3
Frontend build	`vite`	Bundling, HMR, dev server, production build
Python bridge	`litestar-vite`	`VitePlugin` + `InertiaConfig`, asset manifest, type generation, page-props codec
Server framework	`litestar`	Routes, Controllers, Guards, DI, DTOs — returning Inertia responses

You can't skip any of these. Using Inertia with Litestar requires all four, and the skills form a chain: Litestar routes produce page data → ViteConfig.inertia configures the Inertia response layer → Vite-served client bundle mounts the page component → Inertia client takes over for subsequent navigations.

This skill covers that integration end-to-end. For anything that's purely about one layer (e.g., Vite config internals) see the corresponding sibling skill.

When this skill activates

Python files importing litestar_vite.inertia, InertiaConfig, or route handlers with component=
*.tsx / *.vue / *.svelte files importing from @inertiajs/*
createInertiaApp({ resolve, setup }) in a frontend entrypoint
A resources/ or resources/js/pages/ directory alongside a src/py/ — classic litestar-vite + Inertia layout
inertia.config.ts or an InertiaConfig invocation in vite.config.ts
User asks about "building an SPA with a Python backend", "server-driven React/Vue", "form validation errors from Python", "shared auth data across pages"

Code Style Rules

PEP 604 unions in consumer Python modules; use from __future__ import annotations only when the application benefits from it
TypeScript typed pages — generate page-props types via litestar-vite's TypeGen, never hand-roll
Forms via useForm — use the adapter form helper for errors, submission state, and navigation
CSRF via Litestar state — configure Litestar CSRFConfig and wire csrfHeaders() into global Inertia visit options; generated scaffolds already do this, including with cookie_httponly=True
Shared data for auth + flash, never page-specific. Static page props go in InertiaConfig.extra_static_page_props; session-backed props go in extra_session_page_props; request-time flashes use share(request, ...).
camelCase on the wire — define msgspec structs with class Example(msgspec.Struct, rename="camel"); generated TypeScript consumes the serialized names
Partial reloads over full-page reloads when only a subset of props changes (router.reload({ only: ['notifications'] }))
Lazy props for expensive-to-compute page data the user may not need on first paint

Quick Reference

Backend — Python route returning an Inertia page

from __future__ import annotations

from litestar import Controller, get

from app.domain.accounts.guards import requires_active_user
from app.domain.dashboard.schemas import Dashboard


class DashboardController(Controller):
    path = "/dashboard"
    guards = [requires_active_user]

    @get("/", component="dashboard/Index")
    async def index(self, dashboard_service) -> Dashboard:
        return await dashboard_service.get_for_current_user()

→ See references/litestar_integration.md

Client — page component (React)

// resources/js/pages/dashboard/Index.tsx
import { usePage, Head } from "@inertiajs/react";
import type { Dashboard } from "@/generated/api";

export default function DashboardIndex() {
  const { dashboard } = usePage<{ dashboard: Dashboard }>().props;

  return (
    <>
      <Head title="Dashboard" />
      <h1>Welcome, {dashboard.user.name}</h1>
      <p>Your workspace has {dashboard.workspaceCount} projects.</p>
    </>
  );
}

→ See references/protocol.md

App wiring — VitePlugin owns the Inertia bridge

from __future__ import annotations

from litestar import Litestar
from litestar.middleware.session.client_side import CookieBackendConfig
from litestar_granian import GranianPlugin
from litestar_vite import PathConfig, TypeGenConfig, ViteConfig, VitePlugin
from litestar_vite.inertia import InertiaConfig

from app.domain.accounts.schemas import CurrentUser
from app.lib.settings import get_settings


settings = get_settings()
session_backend = CookieBackendConfig(secret=settings.secret_key.encode("utf-8"))
vite = VitePlugin(
    config=ViteConfig(
        mode="hybrid",
        dev_mode=settings.debug,
        paths=PathConfig(
            root=settings.base_dir,
            resource_dir="resources",
            bundle_dir="public",
        ),
        inertia=InertiaConfig(
            root_template="index.html",
            extra_static_page_props={"appName": settings.app_name},
            extra_session_page_props={"currentUser": CurrentUser},
        ),
        types=TypeGenConfig(output="resources/generated"),
    )
)

app = Litestar(
    route_handlers=[DashboardController, ...],
    plugins=[GranianPlugin(), vite],
    middleware=[session_backend.middleware],
)

→ See references/litestar_integration.md for full wiring

Forms — `useForm` with Litestar validation errors

import { useForm } from "@inertiajs/react";

export default function CreateProject() {
  const { data, setData, post, processing, errors } = useForm({
    name: "",
    description: "",
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); post("/projects"); }}>
      <input value={data.name} onChange={(e) => setData("name", e.target.value)} />
      {errors.name && <div className="error">{errors.name}</div>}

      <textarea value={data.description} onChange={(e) => setData("description", e.target.value)} />
      {errors.description && <div className="error">{errors.description}</div>}

      <button type="submit" disabled={processing}>Create</button>
    </form>
  );
}

Inertia validation follows redirect-with-session semantics. Use error(request, field, message) and return InertiaBack(request), or install an exception handler that performs that mapping. A raw 422 response does not populate the next page's errors prop automatically.

Partial reloads — only re-fetch what changed

import { router } from "@inertiajs/react";

// After a background task finishes, reload only notifications:
router.reload({ only: ["notifications"] });

Lazy props — defer expensive data

from litestar import get
from litestar_vite.inertia import lazy

@get("/reports", component="reports/Index")
async def reports_page(self, reports_service) -> dict:
    return {
        "summary": await reports_service.summary(),            # eager
        "fullExport": lazy("fullExport", reports_service.export),
    }

Client fetches fullExport only on router.reload({ only: ["fullExport"] }). Pass the callable, not its result.

Workflow

Step 1 — Wire the bridge

Register GranianPlugin and one VitePlugin(config=ViteConfig(inertia=InertiaConfig(...))). Add session middleware. Do not register a second Inertia plugin in normal app scaffolds; VitePlugin reads ViteConfig.inertia and configures the Inertia bridge.

Step 2 — Define shared props

Put static values in InertiaConfig.extra_static_page_props. Put session-backed values in extra_session_page_props so the integration pulls them from request.session. For request-time flash/auth additions, call share(request, key, value) before returning an Inertia response. These are available on every page via usePage().props without threading them through each handler.

Step 3 — Set up the client entrypoint

resources/js/app.tsx (React) or equivalent: call createInertiaApp() with resolvePageComponent(), render setup, and global visit options:

defaults: {
  visitOptions: (_href, options) => ({
    headers: csrfHeaders(options.headers ?? {}),
  }),
}

Import csrfHeaders from litestar-vite-plugin/helpers.

Step 4 — Build page components

One .tsx / .vue / .svelte file per route, keyed by name. @get(..., component="path/Name") on the Python handler maps to resources/js/pages/path/Name.tsx.

Step 5 — Generate types

litestar assets generate-types (from litestar-vite) reads your Python msgspec/DTO schemas and emits TypeScript types the page components consume directly.

Step 6 — Validate

/ returns text/html (full initial render) on first visit
Subsequent navigations return application/json with Inertia envelope (X-Inertia: true)
DevTools Network tab shows X-Inertia-* response headers
Invalid form input stores errors and redirects back; the next page response exposes errors
Stale asset-version GET requests return 409 plus X-Inertia-Location; non-GET requests continue to the handler
Partial responses omit deferredProps

Guardrails

Don't mix Inertia and plain JSON API routes in the same app surface — pick one per domain. Mixing confuses auth, CSRF, and response shape expectations. If you need both, use separate route prefixes (/api/* for JSON, /dashboard/* for Inertia).
Do not assume useForm adds CSRF headers — wire csrfHeaders() through createInertiaApp({ defaults: { visitOptions } }); the shipped scaffolds do this.
Shared props must be cheap — session props are read on every page request. Cache user lookup; don't hit the DB for feature flags; use Redis for session state.
Version strings matter — Inertia tracks an asset version; mismatched versions force a full page reload. Let litestar-vite generate the version hash; don't hand-roll.
No mixed-framework pages — React + Vue in the same app breaks Inertia's resolver. Pick one adapter per project.
Deep-link routes need real URLs — every Inertia page should have a Litestar route returning it. SPA-only client routes (React Router inside an Inertia page) exist but are an escape hatch.
Don't forget the root template — InertiaConfig.root_template points at the template that mounts the SPA. Default is index.html; Jinja-backed Inertia apps set a Litestar TemplateConfig as well.

Validation Checkpoint

Before shipping an Inertia-integrated Litestar app:

Example — Authenticated dashboard with forms + partial reload

# app/domain/projects/controllers.py
from __future__ import annotations

from litestar import Controller, Request, get, post
from litestar_vite.inertia import InertiaBack, error

from app.domain.accounts.guards import requires_active_user
from app.domain.projects.schemas import Project, ProjectCreate
from app.domain.projects.services import ProjectService


class ProjectsController(Controller):
    path = "/projects"
    guards = [requires_active_user]

    @get("/", component="projects/Index")
    async def index(
        self, projects_service: ProjectService, request: Request
    ) -> dict[str, list[Project]]:
        return {
            "projects": await projects_service.list_for_user(request.user.id),
        }

    @post("/")
    async def create(
        self, data: ProjectCreate, projects_service: ProjectService, request: Request,
    ) -> InertiaBack:
        if await projects_service.exists(name=data.name, owner_id=request.user.id):
            error(request, "name", "You already have a project with this name.")
            return InertiaBack(request)

        await projects_service.create(data.to_dict(), owner_id=request.user.id)
        return InertiaBack(request)

// resources/js/pages/projects/Index.tsx
import { useForm, usePage, router } from "@inertiajs/react";
import type { Project } from "@/generated/api";

export default function ProjectsIndex() {
  const { projects, flash } = usePage<{ projects: Project[]; flash: { success?: string } }>().props;

  const { data, setData, post, processing, errors, reset } = useForm({ name: "", description: "" });

  const onSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    post("/projects", { onSuccess: () => reset() });
  };

  return (
    <>
      {flash.success && <div className="flash">{flash.success}</div>}

      <form onSubmit={onSubmit}>
        <input value={data.name} onChange={(e) => setData("name", e.target.value)} placeholder="Project name" />
        {errors.name && <div className="error">{errors.name}</div>}
        <textarea value={data.description} onChange={(e) => setData("description", e.target.value)} />
        <button disabled={processing}>Create</button>
      </form>

      <button onClick={() => router.reload({ only: ["projects"] })}>Refresh</button>

      <ul>
        {projects.map((p) => <li key={p.id}>{p.name}</li>)}
      </ul>
    </>
  );
}

References Index

Inertia Protocol & Client — Protocol v3, request/response shape, React/Vue/Svelte adapter setup, useForm, usePage, router, partial reloads, lazy props, SSR
Litestar Backend Integration — InertiaConfig, component= route handlers, shared props, redirect responses, validation errors, type generation, SSR server

Cross-Skill References

../litestar-vite/SKILL.md — Vite plugin config, VitePlugin, asset manifest, TypeGen pipeline, HMR (the backbone Inertia sits on)
../litestar/SKILL.md — Controllers, Guards, DI, DTO patterns (the request handling layer)
../advanced-alchemy/SKILL.md — Data services that produce page props
../msgspec/SKILL.md — Struct definitions that TypeGen consumes

Official References

Inertia.js v3 docs: https://inertiajs.com/docs/v3
Tagged Litestar-Vite Inertia docs: https://github.com/litestar-org/litestar-vite/tree/v0.27.0/docs/frameworks/inertia
Client-side setup: https://inertiajs.com/docs/v3/installation/client-side-setup
Release notes: https://github.com/inertiajs/inertia/releases
Tagged litestar-vite Inertia source: https://github.com/litestar-org/litestar-vite/tree/v0.27.0/src/py/litestar_vite/inertia
Tagged Inertia tests: https://github.com/litestar-org/litestar-vite/tree/v0.27.0/src/py/tests/unit/inertia

Shared Styleguide Baseline

Keep this skill focused on the Litestar ↔ Vite ↔ Inertia integration surface. Framework-agnostic React/Vue/Svelte patterns belong in the respective framework skills (if we ever port them) or inertiajs.com docs.

name	litestar-inertia
description	Auto-activate for litestar_vite.inertia, InertiaConfig, component=, @inertia, @inertiajs/*, createInertiaApp, useForm, usePage, Link, router, or pages/. Not for HTMX.

litestar-inertia

More from this repository

More from this repository

Litestar + Inertia.js Integration

When this skill activates

Code Style Rules

Quick Reference

Backend — Python route returning an Inertia page

Client — page component (React)

App wiring — VitePlugin owns the Inertia bridge

Forms — useForm with Litestar validation errors

Partial reloads — only re-fetch what changed

Lazy props — defer expensive data

Workflow

Step 1 — Wire the bridge

Step 2 — Define shared props

Step 3 — Set up the client entrypoint

Step 4 — Build page components

Step 5 — Generate types

Step 6 — Validate

Guardrails

Validation Checkpoint

Example — Authenticated dashboard with forms + partial reload

References Index

Cross-Skill References

Official References

Shared Styleguide Baseline

Litestar + Inertia.js Integration

When this skill activates

Code Style Rules

Quick Reference

Backend — Python route returning an Inertia page

Client — page component (React)

App wiring — VitePlugin owns the Inertia bridge

Forms — useForm with Litestar validation errors

Partial reloads — only re-fetch what changed

Lazy props — defer expensive data

Workflow

Step 1 — Wire the bridge

Step 2 — Define shared props

Step 3 — Set up the client entrypoint

Step 4 — Build page components

Step 5 — Generate types

Step 6 — Validate

Guardrails

Validation Checkpoint

Example — Authenticated dashboard with forms + partial reload

References Index

Cross-Skill References

Official References

Shared Styleguide Baseline

Forms — `useForm` with Litestar validation errors

Forms — `useForm` with Litestar validation errors