https://github.com/psiace/starlive
Build dynamic, real-time web applications with automatic HTMX/Turbo detection and WebSocket streaming
https://github.com/psiace/starlive
fastapi hotwire htmx hypermedia starlette turbo
Last synced: 2 months ago
JSON representation
Build dynamic, real-time web applications with automatic HTMX/Turbo detection and WebSocket streaming
- Host: GitHub
- URL: https://github.com/psiace/starlive
- Owner: PsiACE
- License: apache-2.0
- Created: 2025-06-01T17:37:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-01T20:14:54.000Z (about 1 year ago)
- Last Synced: 2026-04-07T06:36:52.822Z (2 months ago)
- Topics: fastapi, hotwire, htmx, hypermedia, starlette, turbo
- Language: Python
- Homepage:
- Size: 121 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelogithub.config.json
- License: LICENSE
Awesome Lists containing this project
README
# StarLive
> **Universal Hypermedia System for Starlette & FastAPI**
>
> Build dynamic, real-time web applications with automatic HTMX/Turbo detection and WebSocket streaming
[](https://pypi.org/project/starlive/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
StarLive automatically detects HTMX/Turbo clients and provides unified streaming responses with real-time WebSocket updates.
## Features
- **Universal API**: One codebase for both HTMX and Turbo
- **Auto-detection**: Framework detection via request headers
- **Real-time**: WebSocket streaming to all clients
- **Zero config**: Works out of the box
## Installation
```bash
pip install starlive
```
## Quick Start
```python
from starlette.applications import Starlette
from starlette.responses import HTMLResponse
from starlette.routing import Route
from starlive import StarLive, StarLiveMiddleware
starlive = StarLive()
async def homepage(request):
return HTMLResponse(f"""
{starlive.get_scripts()}
Update
""")
async def update_content(request):
if request.state.can_stream():
content = '
Updated!'
if request.state.hypermedia_type == "htmx":
return HTMLResponse(content)
else: # Turbo
stream = starlive.update(content, "#content",
hypermedia_type=request.state.hypermedia_type)
return starlive.stream(stream, request.state.hypermedia_type)
return HTMLResponse("Updated!")
app = Starlette(routes=[
Route("/", homepage),
Route("/update", update_content, methods=["POST"]),
])
app.add_middleware(StarLiveMiddleware, starlive=starlive)
app.router.routes.append(starlive.create_websocket_route())
```
## FastAPI
```python
from fastapi import FastAPI, WebSocket
from starlive import StarLive, StarLiveMiddleware
starlive = StarLive()
app = FastAPI()
app.add_middleware(StarLiveMiddleware, starlive=starlive)
@app.websocket(starlive.ws_route)
async def websocket_endpoint(websocket: WebSocket):
await starlive._websocket_endpoint(websocket)
# Use same handlers as Starlette example
```
## Stream Operations
```python
# All work with both HTMX and Turbo
starlive.append(content, "#target")
starlive.prepend(content, "#target")
starlive.replace(content, "#target")
starlive.update(content, "#target")
starlive.remove("#target")
starlive.before(content, "#target")
starlive.after(content, "#target")
```
## Real-time Updates
```python
# Broadcast to all clients
await starlive.push(
starlive.append('
New message', "#messages"),
to=None
)
# Custom user identification
@starlive.user_id
def get_user_id():
return request.session.get("user_id", "anonymous")
```
## Request Detection
```python
if request.state.hypermedia_type == "htmx":
return HTMLResponse("
HTMX response")
elif request.state.hypermedia_type == "turbo":
return starlive.stream(starlive.update(content, "#target"), "turbo")
else:
return JSONResponse({"data": "value"})
```
## Templates
```python
from starlette.templating import Jinja2Templates
from starlive import starlive_context_processor
templates = Jinja2Templates(directory="templates")
templates.env.globals.update(starlive_context_processor(starlive)())
```
```html
{{ starlive.get_scripts() }}
```
## Examples
```bash
# Interactive demo
uv run starlive-dev
# Specific frameworks
uv run starlive-dev --framework starlette # http://localhost:8001
uv run starlive-dev --framework fastapi # http://localhost:8002
```
## Development
```bash
git clone https://github.com/yourusername/starlive.git
cd starlive
uv sync --dev
```
### Testing
```bash
uv run starlive-test # All tests
uv run starlive-test --framework fastapi # FastAPI only
uv run starlive-test --type e2e # End-to-end only
uv run starlive-test --coverage # With coverage
```
### Code Quality
```bash
uv run ruff check src/ tests/ examples/
uv run ruff format src/ tests/ examples/
```
## License
Apache 2.0 License. See [LICENSE](LICENSE) for details.