| name | spotiarr-sse |
| description | Trigger: SSE, server-sent events, real-time, useServerEvents, live updates, EventSource. spotiarr SSE pattern: frontend EventSource hook, backend AppEventBus, 4 event types. |
| license | Apache-2.0 |
| metadata | {"author":"gentleman-programming","version":"1.0"} |
Activation Contract
Load when adding real-time updates, emitting new SSE events, or extending useServerEvents.
Hard Rules
- Frontend: one SSE connection only — via
useServerEvents (hooks/useServerEvents.ts). Never open additional EventSource instances.
useServerEvents reacts to events by invalidating TanStack Query caches — NOT by writing to Zustand stores.- No reconnection logic exists — if needed, add it inside
useServerEvents, nowhere else.
- Backend: emit SSE events via
infrastructure/messaging/app-event-bus.ts only. Never emit from controllers directly.
useServerEvents must stay mounted inside the authenticated subtree under <TokenGate> (currently AuthenticatedApp in App.tsx). The /api/events SSE endpoint is gated by require-token; mounting SSE before unlock produces 401s. Never hoist useServerEvents above <TokenGate>.
Event Contracts
| Event name | Frontend reaction |
|---|
playlists-updated | invalidate playlists, downloadStatus, all tracks[*] |
download-history-updated | invalidate downloadHistory |
library-updated | invalidate libraryStats, libraryArtists, all libraryArtist[*] |
feed-updated | invalidate releases, followedArtists |
Adding a New SSE Event
- Backend: emit via
app-event-bus.ts with a new event name string
- Frontend: add a listener in
useServerEvents.ts, invalidate the relevant query keys from queryKeys.ts
- Shared: if the event payload needs a typed shape, add it to
packages/shared/src/index.ts
References
- Frontend hook:
apps/frontend/src/hooks/useServerEvents.ts
- Query keys:
apps/frontend/src/hooks/queryKeys.ts
- Backend bus:
apps/backend/src/infrastructure/messaging/app-event-bus.ts
- Backend controller:
apps/backend/src/presentation/controllers/events.controller.ts
- Backend route:
apps/backend/src/presentation/routes/events.routes.ts
