Menü
Auto-activate for litestar_vite.inertia, InertiaConfig, component=, @inertia, @inertiajs/*, createInertiaApp, useForm, usePage, Link, router, or pages/. Not for HTMX.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Basierend auf der SOC-Berufsklassifikation
Auto-activate for advanced_alchemy imports, alembic/, SQLAlchemyAsyncRepositoryService, SQLAlchemyAsyncConfig, repository_type, service_class, filters, or storage. Not for raw SQLAlchemy without Advanced Alchemy — use SQLAlchemy guidance.
Auto-activate for guards=, Guard, ASGIConnection, JWTAuth, JWTCookieAuth, SessionAuth, role or tenant checks, or WebSocket auth. Not for frontend route protection.
Auto-activate for litestar_autowire, AutowirePlugin, AutowireConfig, domain_packages, AutowireIntegration, AutowireLoader, clear_autowire_cache, or automatic controller/listener/task discovery. Not for manual Router composition — keep explicit wiring when discovery adds no value.
Auto-activate for Provide, NamedDependency, SkipValidation, Dependency(skip_validation=True), dependencies=, litestar.di, Dishka FromDishka, Inject, or providers. Not for plain parameters.
Auto-activate for MsgspecDTO, DTOConfig, litestar.dto, OpenAPIConfig, response DTOs, schema_extra, RequestEncodingType, or /schema. Not for persistence models alone.
Auto-activate for litestar_email, EmailPlugin, EmailConfig, EmailService, EmailMessage, SMTPConfig, ResendConfig, SendGridConfig, MailgunConfig, SESConfig, or InMemoryBackend. Not for marketing-campaign platforms — use their dedicated SDKs.
| 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 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.
litestar_vite.inertia, InertiaConfig, or route handlers with component=*.tsx / *.vue / *.svelte files importing from @inertiajs/*createInertiaApp({ resolve, setup }) in a frontend entrypointresources/ or resources/js/pages/ directory alongside a src/py/ — classic litestar-vite + Inertia layoutinertia.config.ts or an InertiaConfig invocation in vite.config.tsfrom __future__ import annotations only when the application benefits from itlitestar-vite's TypeGen, never hand-rolluseForm — use the adapter form helper for errors, submission
state, and navigationCSRFConfig and wire
csrfHeaders() into global Inertia visit options; generated scaffolds already
do this, including with cookie_httponly=TrueInertiaConfig.extra_static_page_props; session-backed props go in extra_session_page_props; request-time flashes use share(request, ...).class Example(msgspec.Struct, rename="camel"); generated TypeScript consumes
the serialized namesrouter.reload({ only: ['notifications'] }))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
// 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
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
useForm with Litestar validation errorsimport { 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.
import { router } from "@inertiajs/react";
// After a background task finishes, reload only notifications:
router.reload({ only: ["notifications"] });
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.
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.
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.
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.
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.
litestar assets generate-types (from litestar-vite) reads your Python msgspec/DTO schemas and emits TypeScript types the page components consume directly.
/ returns text/html (full initial render) on first visitapplication/json with Inertia envelope (X-Inertia: true)X-Inertia-* response headerserrorsGET requests return 409 plus
X-Inertia-Location; non-GET requests continue to the handlerdeferredProps/api/* for JSON, /dashboard/* for Inertia).useForm adds CSRF headers — wire csrfHeaders() through
createInertiaApp({ defaults: { visitOptions } }); the shipped scaffolds do
this.litestar-vite generate the version hash; don't hand-roll.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.Before shipping an Inertia-integrated Litestar app:
ViteConfig.inertia configured with InertiaConfig(...)VitePlugin registered for Vite + Inertialitestar assets generate-typesuseFormerror() and redirect back, or an exception
handler performs the same mappingcsrfHeaders() is wired into global visit optionsdev_mode toggles correctly between dev (Vite HMR) and prod (manifest-resolved assets).vite/ fallback manifest plus
hashed bundles# 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>
</>
);
}
useForm, usePage, router, partial reloads, lazy props, SSRInertiaConfig, component= route handlers, shared props, redirect responses, validation errors, type generation, SSR server../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 consumeslitestar-vite Inertia source: https://github.com/litestar-org/litestar-vite/tree/v0.27.0/src/py/litestar_vite/inertiaKeep 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.