README.md
Rama main · réplica de lectura del repositorio original.
# KAPOW
[](https://github.com/sponsors/ElianCodes)
[](https://discord.gg/M3wzFpGbzp)
[](https://discord.gg/M3wzFpGbzp)?label=Discord&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/M3wzFpGbzp)
Comic-book karaoke queue manager. Hosts spin up a room, guests scan a QR code and search for tracks, the crowd votes songs up the queue, and the host runs the night from a dedicated control booth.
## Stack
- **[TanStack Start](https://tanstack.com/start)** — React SSR framework with file-based routing
- **[TanStack Router](https://tanstack.com/router) + [TanStack Query](https://tanstack.com/query)** — type-safe routing and server-state management
- **[Supabase](https://supabase.com)** — PostgreSQL database with realtime subscriptions for live queue/vote sync
- **[Tailwind CSS v4](https://tailwindcss.com)** — styling
- **[dnd-kit](https://dndkit.com)** — drag-and-drop queue reordering (host view)
- **YouTube Data API v3** — song search
## How it works
1. Host creates a room → gets a host token, a 6-character join code, and a QR code
2. Guests join via the code or QR → search YouTube for karaoke tracks → add to queue with their name
3. Everyone votes; highest-voted pending song rises to the top
4. Host manages playback from `/host/:code`, drives the TV display at `/display/:code`
## Environment
Create a `.env` file at the project root:
```bash
SUPABASE_URL=
SUPABASE_PUBLISHABLE_KEY=
SUPABASE_DB_PASSWORD=
YOUTUBE_API_KEY=
```
## Development
```bash
npm install
npm run dev # starts on http://localhost:3000
```
## Database
Migrations live in `supabase/migrations/` and are the source of truth. `supabase/schema.sql` is kept as a reference snapshot only.
### Local
Requires [Docker](https://www.docker.com) and the [Supabase CLI](https://supabase.com/docs/guides/cli).
```bash
npm run db:start # boot local Supabase stack
npm run db:reset # apply migrations from scratch
npm run db:lint # lint schema for issues
npm run db:test # reset + lint in one step
npm run db:stop # tear down
```
### Remote
```bash
npx supabase link --project-ref <your-project-ref> -p "$SUPABASE_DB_PASSWORD"
npm run db:push:remote
```
### CI
- `.github/workflows/supabase-db.yml` — boots a local Supabase stack on every PR and main push, runs `db reset` + `db lint`
- `.github/workflows/supabase-db-deploy.yml` — pushes migrations to hosted Supabase on merge; requires repository secrets `SUPABASE_ACCESS_TOKEN`, `SUPABASE_PROJECT_REF`, `SUPABASE_DB_PASSWORD`
## Build
```bash
npm run build
npm run preview
```
## Docker
The published image is [`getcoral/kapow`](https://hub.docker.com/r/getcoral/kapow):
```bash
docker run -p 3000:3000 \
-e SUPABASE_URL=https://your-project.supabase.co \
-e SUPABASE_PUBLISHABLE_KEY=your-key \
-e YOUTUBE_API_KEY=your-key \
getcoral/kapow:latest
```
Or build it yourself:
```bash
docker build -t kapow .
```
Published automatically to [`getcoral/kapow`](https://hub.docker.com/r/getcoral/kapow) on Docker Hub on every release via GitHub Actions.
## Code quality
```bash
npm run lint # Biome lint
npm run format # Biome format
npm run check # Biome lint + format together
npm test # Vitest
```
## Routes
| Route | Description |
|---|---|
| `/` | Landing — create or join a room |
| `/room/:code` | Guest view — search songs, add to queue, vote |
| `/host/:code?token=` | Host control booth — manage queue, advance songs |
| `/display/:code` | TV display — now playing, full-screen comic mode |