title: "contributing" description: "contribute to plyr.fm development"#

plyr.fm is open source. development happens on GitHub (mirrored to tangled.org). contributions welcome — fork the repo and open a PR.

using a coding assistant?#

if you're using Claude Code, Cursor, Codex, or similar — copy the prompt below into your assistant to get oriented:

i want to contribute to plyr.fm. the repo is at https://github.com/zzstoatzz/plyr.fm

read the CLAUDE.md at the repo root for project context, then read STATUS.md
for active tasks. fork the repo, make your change on a branch, run linting
(just backend lint / just frontend check), add tests for bug fixes, and open a PR.

the stack is FastAPI + SvelteKit + Postgres + Redis. use `uv` for Python, `bun`
for frontend, and `just` as the task runner. see backend/.env.example for all
environment variables.

or install the contribute skill for richer agent context.

prerequisites#

• uv (Python 3.11+)
• bun (frontend)
• just (task runner)
• docker (for Redis and test databases)

quickstart#

# fork on github, then clone your fork
gh repo fork zzstoatzz/plyr.fm --clone
cd plyr.fm

# install dependencies
uv sync
cd frontend && bun install && cd ..

# configure environment
cp backend/.env.example backend/.env
# edit backend/.env — see the setup guide linked below for details

running the stack#

# start redis (required for background tasks)
just dev-services

# terminal 1 — backend (port 8001, hot reloads)
just backend run

# terminal 2 — frontend (port 5173, hot reloads)
just frontend run

the backend needs a Postgres connection. you can use the Neon dev instance or a local Postgres — set DATABASE_URL in your .env. see backend/.env.example for all configuration options and the local development setup guide for detailed walkthrough.

workflow#

1. check STATUS.md for active tasks
2. open an issue describing the change
3. fork the repo, branch from main, make your changes
4. open a PR from your fork

useful commands#

just backend run          # start backend
just frontend run         # start frontend
just dev-services         # start redis
just backend test         # run tests (spins up isolated postgres + redis)
just backend lint         # type check + ruff
just frontend check       # svelte type check
just backend migrate-up   # apply database migrations

conventions#

• type hints required everywhere (Python and TypeScript)
• async everywhere — never block the event loop
• lowercase aesthetic in naming, docs, and commits
• SvelteKit with Svelte 5 Runes ($state, $derived, $effect)
• use uv for Python (never pip)
• add regression tests when fixing bugs

detailed internal documentation (environment setup, deployment, architecture) is in docs-internal/.