mattyfaz/cubestats repository overview

⁠cubestats

A self-hosted stats viewer for csTimer⁠ exports. Import your csTimer JSON, browse your solve history and see analytics.

⁠Features

• Dashboard — best/avg5/avg12/avg100 with live filters by session and puzzle type
• CSTimer Import - Import / Export csTimer data
• History — searchable, sortable solve table with row-level delete
• Analytics — solve-time distribution, calendar heatmap, time-of-day breakdown
• Trends — rolling averages and session comparisons over time
• Sessions — per-session detail pages
• Built-in timer — WCA-compliant scrambles via cubing.js⁠, inspection countdown
• Goals — track targets for any stat metric
• Import — drag-and-drop csTimer JSON; deduplicates on re-import
• Multi-puzzle — 2x2 through 7x7, megaminx, pyraminx, skewb, square-1
• Light & dark mode

⁠Quick start (Docker)

Single-container, no compose required. Pick a password and a long random secret:

docker run -d --name cubestats \
  -p 3000:3000 \
  -v cubestats-data:/app/data \
  -e NUXT_AUTH_PASS='<your-password>' \
  -e NUXT_AUTH_SECRET='<a-long-random-string>' \
  --restart unless-stopped \
  mattyfaz/cubestats:latest

Open http://localhost:3000⁠, log in, then drop a csTimer export onto the Import page.

⁠Or with Docker Compose

services:
  cubestats:
    image: mattyfaz/cubestats:latest
    ports:
      - 3000:3000
    environment:
      - NUXT_AUTH_PASS=<your-password>           # required — server refuses to boot with "changeme", "admin", or "password"
      - NUXT_AUTH_SECRET=<a-long-random-string>  # required — must not start with "change-this", "dev-secret", or "changeme"
    volumes:
      - cubestats-data:/app/data
    restart: unless-stopped

volumes:
  cubestats-data:

The image is published to Docker Hub⁠ and GHCR⁠ for linux/amd64 and linux/arm64. Your data lives in the cubestats-data volume — back up cubestats.db from inside it to keep your solves safe.

⁠Local development

Requires Node 22+. Database is a local SQLite file — no external services needed.

npm install
cp .env.example .env
# Edit .env — set NUXT_AUTH_PASS / NUXT_AUTH_SECRET to anything
npm run db:migrate    # creates data/cubestats.db
npm run dev

⁠Environment variables

⁠Exporting from csTimer

In csTimer, open the export menu and choose Export. Save the resulting JSON file and drag it onto the Import page in cubestats.

⁠Scripts

npm run dev          # Dev server
npm run build        # Production build
npm run preview      # Preview production build
npm run test         # Vitest watch
npm run test:run     # Vitest single run
npm run db:generate  # Generate Drizzle migration from schema
npm run db:migrate   # Apply migrations
npm run db:studio    # Drizzle Studio

⁠Contributing

See CONTRIBUTING.md⁠. Security issues: see SECURITY.md⁠.

⁠License

MIT⁠

⁠Acknowledgements

• csTimer⁠ — the timer this tool reads from
• cubing.js⁠ — scramble generation