SPRAG Documentation
Learn how to build full-stack Python web apps with SPRAG.
What is SPRAG
One Python codebase, two runtimes — server and browser — with no JavaScript to write.
Installation
Prerequisites and setup for SPRAG.
First App
Walk through the default counter app from scaffold to build.
Project Structure
What each file in a SPRAG project does and when you need it.
Two Runtimes
The core concept — one Python codebase compiles to two runtimes, server and browser.
Routes
File-based routing, route modes, dynamic segments, and the page manifest.
Content Collections
Scaffold markdown-backed route trees with automatic static path expansion.
Controllers
Server-side request handling — load, actions, HTTP routes, and socket events.
Stores
Cross-runtime shared state — one declaration, works on server and browser.
Auth
Session management, authentication guards, and login/logout flows.
Uploads
File uploads from the browser — form-based, programmatic, chunked, and progress tracking.
Realtime
WebSocket communication — server push, browser subscription, topics, and the signal-then-refetch pattern.
Codegen
What Python constructs compile to JavaScript — the complete reference for browser-side code.
Specter Overview
The server-side runtime under SPRAG — when and why to reach for raw Specter.
Services
Long-lived server-side processes with managed lifecycle, concurrency, and event subscriptions.
Schemas
Declarative payload validation for actions and custom endpoints.
Queues
Background job processing with bounded concurrency, progress reporting, and cancellation.
State Primitives
create_store vs create_model vs create_cache — when to use each, semantics, and subscription patterns.
Handlers & SocketIngress
Class-based socket event binding, priority ordering, and multi-subscriber fanout.
Watchers & ManagedProcess
Polling and streaming observation loops with retry/backoff, plus supervised subprocesses.
Ragot Overview
The browser runtime that SPRAG's codegen targets — what it is and when to reach for it directly.
Components
DOM-owning browser classes — render ui trees, handle events, manage refs.
Modules
Non-visual browser lifecycle — server calls, sockets, timers, and state management.
UI Primitives
Element factories, keyed lists, grids, and lazy images — the building blocks of Component render trees.
Decorators
Structural transforms — debounce, throttle, animate, virtual scroll, and infinite scroll.
State Stores
Deep dive into createStateStore — browser-side shared state and selectors.
Payload Design
What goes in load(), what stays on the server, and how to avoid bloating your pages.
Advanced DOM & Interop
DOM helpers, third-party interop, and lifecycle-safe manual DOM operations.
Deployment
Building, optimizing, and deploying SPRAG apps — static hosting, WSGI, and WebSocket modes.
Forms
The SPRAG form convention — DOM-owned inputs, Module-owned state, validation, and file uploads.
Background Jobs
Processing long-running work with queues, progress tracking, and cancellation.
CLI Reference
Complete reference for the `sprag` command-line interface.