Litestar Realtime

---
name: litestar-realtime
description: "Auto-activate for @websocket, WebSocket, ServerSentEvent, SSE, ChannelsPlugin, ChannelsBackend, stream_pubsub, channel subscriptions, realtime events, or cross-process fan-out. Use when implementing Litestar WebSockets, SSE, Channels, or event publishing. Not for polling-only APIs or frontend socket clients alone."
---

# Litestar Realtime

Use this skill for WebSockets, SSE, ChannelsPlugin backends, realtime event contracts, and fan-out from workers or services.

## Code Style Rules

- Use plain WebSocket handlers for one-off streams.
- Use ChannelsPlugin when dynamic topics, history, or cross-process fan-out matter.
- Choose the backend that matches the existing stack.
- Treat WebSocket auth separately from HTTP header auth constraints.

## Quick Reference

- WebSocket and Channels patterns: [websockets.md](references/websockets.md)
- Event contract patterns: [realtime-events.md](references/realtime-events.md)
- Pair with [litestar-auth-guards](../litestar-auth-guards/SKILL.md) for socket auth.

<workflow>

## Workflow

1. Choose WebSocket, SSE, or Channels based on delivery needs.
2. Define event contracts before wiring transport.
3. Select a backend that fits the project stack.
4. Test connection, auth, fan-out, disconnect, and error paths.

</workflow>

<guardrails>

## Guardrails

- Do not force Redis into a PostgreSQL-only stack just for Channels.
- Do not assume browsers can set arbitrary WebSocket headers.
- Do not publish untyped event dicts across service boundaries.
- Do not use request-scoped resources after the socket lifecycle ends.

</guardrails>

<validation>

## Validation Checkpoint

- [ ] Transport choice matches the user experience.
- [ ] Event payloads are typed.
- [ ] Backend choice matches the stack.
- [ ] Auth and disconnect behavior are tested.

</validation>

<example>

## Example

```python
from litestar import websocket

@websocket("/ws")
async def stream(socket: WebSocket) -> None:
    await socket.accept()
    await socket.send_json({"type": "ready"})
```

</example>

## References Index

- [websockets.md](references/websockets.md)
- [realtime-events.md](references/realtime-events.md)

## Official References

- <https://docs.litestar.dev/> - Litestar documentation
- <https://docs.litestar.dev/latest/reference/> - Litestar API reference

## Shared Styleguide Baseline

- [General](../litestar-styleguide/references/general.md)
- [Python](../litestar-styleguide/references/python.md)
- [Litestar](../litestar-styleguide/references/litestar.md)