zzstoatzz.io
audio streaming app
plyr.fm
1---
2title: "contributing"
3description: "contribute to plyr.fm development"
4---
5
6plyr.fm is open source. development happens on [GitHub](https://github.com/zzstoatzz/plyr.fm) (mirrored to [tangled.org](https://tangled.org/zzstoatzz.io/plyr.fm)). contributions welcome — fork the repo and open a PR.
7
8## using a coding assistant?
9
10if you're using Claude Code, Cursor, Codex, or similar — copy the prompt below into your assistant to get oriented:
11
12```
13i want to contribute to plyr.fm. the repo is at https://github.com/zzstoatzz/plyr.fm
14
15read the CLAUDE.md at the repo root for project context, then read STATUS.md
16for active tasks. fork the repo, make your change on a branch, run linting
17(just backend lint / just frontend check), add tests for bug fixes, and open a PR.
18
19the stack is FastAPI + SvelteKit + Postgres + Redis. use `uv` for Python, `bun`
20for frontend, and `just` as the task runner. see backend/.env.example for all
21environment variables.
22```
23
24or install the [contribute skill](https://github.com/zzstoatzz/plyr.fm/tree/main/skills/contribute) for richer agent context.
25
26## prerequisites
27
28- [uv](https://docs.astral.sh/uv/) (Python 3.11+)
29- [bun](https://bun.sh/) (frontend)
30- [just](https://just.systems/) (task runner)
31- [docker](https://www.docker.com/) (for Redis and test databases)
32
33## quickstart
34
35```bash
36# fork on github, then clone your fork
37gh repo fork zzstoatzz/plyr.fm --clone
38cd plyr.fm
39
40# install dependencies
41uv sync
42cd frontend && bun install && cd ..
43
44# configure environment
45cp backend/.env.example backend/.env
46# edit backend/.env — see the setup guide linked below for details
47```
48
49### running the stack
50
51```bash
52# start redis (required for background tasks)
53just dev-services
54
55# terminal 1 — backend (port 8001, hot reloads)
56just backend run
57
58# terminal 2 — frontend (port 5173, hot reloads)
59just frontend run
60```
61
62the backend needs a Postgres connection. you can use the [Neon](https://neon.tech) dev instance or a local Postgres — set `DATABASE_URL` in your `.env`. see [`backend/.env.example`](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/.env.example) for all configuration options and the [local development setup guide](https://github.com/zzstoatzz/plyr.fm/blob/main/docs-internal/local-development/setup.md) for detailed walkthrough.
63
64## workflow
65
661. check [`STATUS.md`](https://github.com/zzstoatzz/plyr.fm/blob/main/STATUS.md) for active tasks
672. [open an issue](https://github.com/zzstoatzz/plyr.fm/issues) describing the change
683. fork the repo, branch from `main`, make your changes
694. open a PR from your fork
70
71## useful commands
72
73```bash
74just backend run # start backend
75just frontend run # start frontend
76just dev-services # start redis
77just backend test # run tests (spins up isolated postgres + redis)
78just backend lint # type check + ruff
79just frontend check # svelte type check
80just backend migrate-up # apply database migrations
81```
82
83## conventions
84
85- **type hints** required everywhere (Python and TypeScript)
86- **async everywhere** — never block the event loop
87- **lowercase aesthetic** in naming, docs, and commits
88- SvelteKit with **Svelte 5 Runes** (`$state`, `$derived`, `$effect`)
89- use `uv` for Python (never `pip`)
90- add regression tests when fixing bugs
91
92detailed internal documentation (environment setup, deployment, architecture) is in [`docs-internal/`](https://github.com/zzstoatzz/plyr.fm/tree/main/docs-internal).