Type-Safe API Client (Orval)¶

FastSvelte keeps the frontend and backend in sync with a TypeScript API client generated from the backend's OpenAPI spec by Orval. Change a Pydantic model or route, regenerate, and the TypeScript compiler catches any breakage at compile time.

Regenerate after backend changes¶

cd frontend
npm run generate   # reads the OpenAPI spec and regenerates the client (backend must be running)

Generated code lives in frontend/src/lib/api/gen/.

Don't edit generated code by hand

Everything under gen/ is overwritten on every generate. Hand edits are silently lost.

How it works¶

Define Pydantic models and routes with response_model and operation_id:
```
@router.post("", response_model=NoteResponse, operation_id="createNote")
async def create_note(data: CreateNoteRequest, ...): ...
```
- response_model → the response type in the OpenAPI spec
- operation_id → the generated TypeScript function name
FastAPI generates the OpenAPI spec from the decorators and models.
Orval reads the spec and emits typed functions and models.

Import and use them with full type safety:

import { createNote } from "$lib/api/gen/notes";
import type { CreateNoteRequest, NoteResponse } from "$lib/api/gen/model";

const note: NoteResponse = await createNote({ title: "My Note", content: "..." });

When you change the backend and regenerate, the TypeScript compiler flags any frontend code that no longer matches.