From e0c42dd5acaaf5ebefb5787ec307da911b0f086c Mon Sep 17 00:00:00 2001 From: tgiachi Date: Thu, 12 Nov 2026 11:45:20 +0100 Subject: [PATCH] docs(web): how to run and build the web app - README section for the web client: how to run it next to sondad, what it does today, the commands - the greeting on Home is read once per visit (lint: no Date during render) - checked against a real sondad: login, renewal and spent refresh tokens, media URLs with Range, listens, search, and the provider-off answers --- README.md | 19 +++++++++++++++++-- web/src/pages/HomePage.tsx | 4 +++- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 43cdaf2..329d693 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Sonda is a privacy-first, self-hosted music server written in Go. It streams the It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account. -> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). Radio queues, a web client and OpenSubsonic compatibility are not built yet (see [What is not there yet](#what-is-not-there-yet)). The API may still change. +> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). Radio queues and OpenSubsonic compatibility are not built yet, and the web client in `web/` is a work in progress (see [What is not there yet](#what-is-not-there-yet) and [Web app](#web-app)). The API may still change. ## What works today @@ -27,7 +27,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr ## What is not there yet -Radio queues, a web client, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. +Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client exists (see [Web app](#web-app)) but `sondad` does not serve it yet, and it has no Discover or admin screens yet. ## Requirements @@ -271,6 +271,20 @@ Back up the database and `sonda.toml`. Your music stays wherever you keep it. - **PostgreSQL:** `pg_dump` the database. - `sonda.toml` holds the secret that signs tokens; treat the copy like a password. +## Web app + +A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. `sondad` does not serve it yet, so for now it runs next to the server: + +```bash +cd web +npm install +SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api is proxied to Sonda +``` + +What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys and a full-screen player. Artist pages show the Wikipedia text, similar artists and tags when those providers are on, each with its credit, and the photo credit next to the photo. It reports one listen per play. There are four themes (Sonda, Tokyo Night, Gruvbox dark and Gruvbox light) and two languages (English and Italian), both chosen in Settings. + +More commands, all run in `web/`: `npm test`, `npm run build`, and `npm run gen:api`, which rebuilds `src/api/schema.d.ts` from the OpenAPI spec (it fetches the generator with `npx`, so it needs the network once). Discover, the admin screens and serving the app from the binary come later. + ## Development ```bash @@ -309,6 +323,7 @@ internal/usersettings/ the settings that belong to one user internal/storage/ SQLite and PostgreSQL through bun, the repositories internal/streaming/ opening a track's file safely migrations/ SQL migrations, one folder per database +web/ the web client (React, Vite, shadcn/ui) ``` The API description is `internal/api/openapi/openapi.yaml`, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (`additionalProperties: false`), so a field added in the code and forgotten in the spec fails the build. diff --git a/web/src/pages/HomePage.tsx b/web/src/pages/HomePage.tsx index f9ad405..79c601d 100644 --- a/web/src/pages/HomePage.tsx +++ b/web/src/pages/HomePage.tsx @@ -29,6 +29,8 @@ export default function HomePage() { const albums = useAlbumList({ pageSize: SHELF }) const artists = useArtistList(undefined, { pageSize: SHELF }) const [playError, setPlayError] = useState(null) + // Read once per visit of the page: the greeting does not need to change while it is open. + const [hour] = useState(() => new Date().getHours()) // The same song listened to again and again is one tile; the most recent listen comes first. const recent = [...new Map((history.data?.items ?? []).map((l) => [l.track.id, l.track])).values()].slice(0, RECENT) @@ -53,7 +55,7 @@ export default function HomePage() { return (
-

{t(greetingKey(new Date().getHours()))}

+

{t(greetingKey(hour))}

{libraryEmpty ? ( {t('home.emptyLibrary')}