Violit Documentation

Introduction

What is Violit?

A reactive Python framework that now ships with more of the app stack built in

Violit lets you build reactive apps in plain Python, but the story is bigger now than 'no JavaScript required'. It already includes ORM, auth, Tailwind-first styling hooks, background jobs, interval timers, and desktop mode.

The architectural difference is still the point: unlike Streamlit's full rerun model, Violit tracks dependencies and updates only the widgets that actually depend on changed State.

Fine-Grained Updates

Only widgets bound to changed State rerender

Built-in ORM

Use SQLModel models through vl.App(db=...) and app.db

Built-in Auth

Tailwind-First Styling

Start with cls, then add_css(), configure_widget(), and part_cls

Background + Interval

Handle long jobs and periodic timers without blocking the UI

Web and Desktop

Browser, lite mode, and native window from the same app

Quick Start

A tiny app that already feels closer to a real product

The easiest way to start now is with the Violit CLI. Install the package, create a starter project, then run it with hot reload so you can edit and learn in one loop.

pip install violit
violit create my_app
cd my_app
violit run main.py --reload --localhost

TIP

violit create gives you a working starter project immediately. Then use violit run main.py --reload --localhost while you edit so the page stays in a fast feedback loop on your local machine.

Run Options

The CLI is a thin wrapper around running your file with Python. Any flags after the script path are passed to app.run(), so the same runtime options work in both styles.

python main.py --reload --localhost
violit run main.py --reload --localhost

violit run main.py --help
violit run main.py --port 8010
violit run main.py --native
violit run main.py --lite
violit run main.py --make-migration "add_users"

INFO.

If you already know python main.py --reload, you can switch to violit run main.py --reload without learning a different flag set. --localhost, --port, --native, --lite, and migration flags are forwarded to app.run().

Output

Ship Violit faster

This tiny example still has real state and live input.

Interactions

Log one more

main.py

import violit as vl

app = vl.App(title="Starter", theme="violit_light_jewel")

name = app.text_input("Project name", value="Violit")
count = app.state(3)

app.text(lambda: f"Ship {name.value} faster")
app.metric("Interactions", count)
app.button("Log one more", on_click=lambda: count.set(count.value + 1))

app.run()

App Constructor Options

Major parameters available for vl.App().

Parameter	Type	Default	Description
`title`	str	`"Violit App"`	App title (Browser tab, Native window title)
`theme`	str	`"violit_light_jewel"`	Theme preset name (20+ built-in presets)
`mode`	str	`"ws"`	"ws" (WebSocket) or "lite" (HTMX based HTTP)
`root_path`	str	`""`	Base path when the app is served behind a proxy subpath such as /internal/tools
`db`	str \| None	`None`	SQLite path or DB URL for built-in ORM support
`migrate`	str \| bool	`"auto"`	Migration mode for ORM: auto, force, files, or False
`container_width`	str	`"800px"`	Content max width. "none" for full width
`icon`	str	`"💎"`	App icon (Emoji or .ico file path)
`use_cdn`	bool	`False`	True: Use CDN, False: Local vendor (Offline capable)
`allow_selection`	bool	`True`	Allow text selection
`animation_mode`	str	`"soft"`	Animation mode: "soft" or "hard"
`width`	int	`1024`	Native window width (--native mode)
`height`	int	`768`	Native window height (--native mode)

app = vl.App(
    title="Operations Console",
    theme="violit_light_jewel",
    root_path="/internal/tools",
    db="./app.db",
    migrate="auto",
    container_width="960px",
    icon="🚀",
    use_cdn=False,          # Offline capable
    animation_mode="soft",  # Soft transitions
)

TIP

All vendor libraries (Web Awesome, Plotly, AG Grid, etc.) are bundled locally, enabling full offline operation with use_cdn=False (default).

INFO.

If you are evaluating current Violit, jump next to ORM & Auth, Background & Interval, and Styling. Those pages cover the newer app-stack APIs in the right places.

FastAPI Customization

Use Violit as the reactive UI layer while still controlling the underlying FastAPI app when deployment or integration needs it.

Violit keeps its FastAPI instance available as app.fastapi. That means you can stay inside Violit for normal UI work, then drop to FastAPI only for the server-level controls you actually need.

Parameter	Type	Default	Description
`root_path`	str	`""`	Constructor option for reverse-proxy and subpath deployments, for example /internal/tools
`app.add_middleware(...)`	method	`—`	Registers FastAPI or Starlette middleware directly on the underlying server app
`app.fastapi`	FastAPI	`—`	Direct access when you need mounts, middleware, or other FastAPI integrations
`app.run(port=8010)`	runtime	`8000`	Custom port remains a runtime concern rather than a constructor option

from fastapi.middleware.cors import CORSMiddleware
import violit as vl

app = vl.App(
    title="Behind Proxy",
    root_path="/internal/tools",
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.text("Hello from Violit")
app.run(port=8010)

INFO.

If you need more than middleware, the underlying FastAPI instance is still available as app.fastapi. For example, you can mount extra static assets or add custom integrations without giving up Violit's widget layer.

TIP

A practical split is simple: use root_path for subpath deployment, use app.run(port=...) or --port for the listening port, and use app.add_middleware(...) only when you truly need server-level behavior.