Scaffold a new Caspian project (FastAPI-powered reactive Python framework).
npm install create-caspian-apppp.rpc()
bash
npx create-caspian-app@latest
`
Example prompts you’ll see in the wizard:
- Project name
- Tailwind CSS
- Prisma ORM
- Backend only (no frontend assets)
- TypeScript support
$3
`bash
cd my-app
npm run dev
`
---
What “Reactive Python” looks like
A Caspian page can be plain HTML with reactive directives, plus a small
---
Why developers choose Caspian
$3
Your logic runs in native async Python and can leverage FastAPI/Starlette features (DI, middleware, validation, etc.) without a separate JS backend.
$3
Start with simple HTML-first development for speed and clarity, then adopt Vite + NPM + TypeScript when you need richer libraries or complex bundles.
$3
Define async def actions and call them directly from the browser; Caspian handles serialization, security, and async execution.
$3
Routes are determined by files in src/app, supporting dynamic segments ([id]), catch-alls ([...slug]), route groups ((auth)), and layout nesting via layout.html.
$3
Define a single Prisma schema and generate a typed Python client—autocomplete-first database access without boilerplate.
$3
Built-in CSRF protection, strict Origin validation, HttpOnly cookies, and a session-based auth model with RBAC support.
---
Installation & DX setup (VS Code)
For the best developer experience, Caspian’s docs recommend:
- Caspian Official Framework Support (component autocompletion + snippets)
- Prisma schema formatting/highlighting
- Tailwind CSS IntelliSense & class sorting
---
Core concepts
$3
Caspian uses file-system routing under src/app:
| File Path | URL Path |
| ------------------------------- | ------------- |
| src/app/index.html | / |
| src/app/about/index.py | /about |
| src/app/blog/posts/index.html | /blog/posts |
#### Dynamic segments
`txt
src/app/users/[id]/index.py -> /users/123
`
#### Catch-all segments
`txt
src/app/docs/[...slug]/index.py -> /docs/getting-started/setup
`
#### Route groups (organize without changing URLs)
`txt
src/app/(auth)/login/index.py -> /login
src/app/(auth)/register/index.py -> /register
`
#### Nested layouts
Layouts wrap pages and preserve state during navigation:
- Root: src/app/layout.html
- Nested: e.g., /dashboard/settings inherits root + dashboard layout automatically
---
$3
Components are Python functions decorated with @component.
#### Atomic component (best for buttons, badges, icons, etc.)
`py
from casp.html_attrs import get_attributes, merge_classes
from casp.component_decorator import component
@component
def Container(**props):
incoming_class = props.pop("class", "")
final_class = merge_classes("mx-auto max-w-7xl px-4", incoming_class)
children = props.pop("children", "")
attributes = get_attributes({"class": final_class}, props)
return f'{children}'
`
DX speed tip: the VS Code extension can generate boilerplate via a snippet like caspcom.
#### Type-safe props (TypeScript-like autocomplete)
`py
from typing import Literal, Any
from casp.component_decorator import component
ButtonVariant = Literal["default", "destructive", "outline"]
ButtonSize = Literal["default", "sm", "lg"]
@component
def Button(
children: Any = "",
variant: ButtonVariant = "default",
size: ButtonSize = "default",
**props,
) -> str:
# merge classes + attrs here
return f""
`
HTML templates for complex UI
For larger layouts or reactive UIs, bridge to an HTML file:
`py
from casp.component_decorator import component, render_html
@component
def Counter(**props):
return render_html("Counter.html", **props)
`
---
$3
Caspian is built on PulsePoint, a lightweight reactive DOM engine, plus Caspian-specific helpers for full-stack workflows.
Core directives/primitives include:
- pp-component, pp-spread, pp-ref, pp-for, pp.state, pp.effect, pp.ref, pp-ignore
#### pp.rpc(functionName, data?)
The bridge to your Python backend. Caspian handles:
- smart serialization (JSON ↔ FormData when File is present)
- auto-redirects when server returns redirect headers
- X-CSRF-Token injection for security
#### searchParams
A reactive wrapper around URLSearchParams that updates the URL without full reloads.
#### Navigation
Caspian intercepts internal links for client-side navigation; for programmatic navigation use:
`js
pp.redirect("/dashboard");
`
---
Backend: Async Server Actions (RPC)
Decorate async def functions with @rpc, then call them from the client using pp.rpc().
Backend (src/app/todos/index.py)
`py
from casp.rpc import rpc
from casp.validate import Validate
from src.lib.prisma.db import prisma
@rpc()
async def create_todo(title):
if Validate.with_rules(title, "required|min:3") is not True:
raise ValueError("Title must be at least 3 chars")
new_todo = await prisma.todo.create(data={
"title": title,
"completed": False
})
return new_todo.to_dict()
@rpc(require_auth=True)
async def delete_todo(id, _current_user_id=None):
await prisma.todo.delete(where={"id": id})
return {"success": True}
`
Frontend (src/app/todos/index.html)
`html
`
---
Database: Prisma ORM
Caspian uses a Prisma schema as the single source of truth and generates a typed Python client. It is designed to translate Prisma syntax into optimized SQL without requiring the heavy Prisma Engine binary.
Schema (prisma/schema.prisma)
`prisma
model User {
id String @id @default(cuid())
email String @unique
name String?
posts Post[]
createdAt DateTime @default(now())
}
model Post {
id String @id @default(cuid())
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId String
}
`
$3
`py
from src.lib.prisma.db import prisma
users = prisma.user.find_many()
`
The docs also describe connection pooling and common CRUD patterns (create, find, update, delete), plus aggregations and transactions.
---
Authentication (session-based, secure defaults)
Caspian includes session-based authentication with HttpOnly cookies and RBAC-friendly conventions.
Configure auth in main.py
- global protection toggle (is_all_routes_private)
- public routes whitelist
- auth routes (signin/signup)
- default redirects
The global auth object provides:
- auth.sign_in(data, redirect_to?)
- auth.sign_out(redirect_to?)
- auth.is_authenticated()
- auth.get_payload()
---
CLI reference
$3
`bash
npx create-caspian-app
`
$3
- --backend-only skip frontend assets
- --tailwindcss Tailwind CSS v4 + PostCSS + globals.css
- --typescript TypeScript support with Vite + tsconfig.json
- --mcp Model Context Protocol server scaffolding (AI Agents)
- --prisma Prisma ORM integration + sample schema
$3
Generate strict Python data classes (Pydantic) from your Prisma schema:
`bash
npx ppy generate
`
$3
`bash
npx casp update project
`
Tip: use excludeFiles in caspian.config.json to prevent overwrites during updates.
---
Built-in icon workflow (ppicons)
Caspian integrates ppicons (Lucide-based), offering 1,500+ icons and an instant add command:
`bash
npx ppicons add Rocket
`
Then use in HTML:
`html
`
---
Project structure (generated by the CLI)
High-level layout:
- main.py — FastAPI app & ASGI entry
- caspian.config.json — project config
- prisma/ — schema + seed scripts
- src/ — app routes, pages, styles, shared libs
- public/` — static assets served directly