Pomodoro
A browser-based Pomodoro timer and clock built with React, TypeScript, and Vite.
Stage 1
- Live clock
- 25-minute focus sessions
- 5-minute short breaks and 15-minute long breaks
- Start, pause, resume, and reset controls
- Long break after every four completed focus sessions
- Accurate countdown after background-tab throttling
- Sound notification when a segment ends
Stage 2
- Custom focus, short-break, and long-break durations
- Automatic focus-to-break sequencing, enabled by default with an opt-out setting
- Ten built-in themes, including minimalist black/white and animated lava-style backgrounds
- Adjustable background overlay and a separate persistent clock-color override
- Four clock and timer font styles
- Live customization preview with one-click reset
- Automatic settings persistence in IndexedDB
- Slowly pulsing indicator for the active focus session
- Browser fullscreen control and a distraction-free focus mode
All preferences stay in the browser. No account or backend is required.
Development
npm install
npm run dev
Quality checks:
npm test
npm run lint
npm run build
Container
Run the published image on the default port 5120:
docker run --rm -p 5120:5120 ghcr.io/kr0sh512/pomodoro:latest
Or build it locally:
docker build -t pomodoro:local .
docker run --rm -p 5120:5120 pomodoro:local
GitHub Actions tests the project and publishes multi-architecture images for linux/amd64 and
linux/arm64 to GHCR on pushes to main and version tags. Published tags include latest,
main, version tags, and sha-<commit>.
Architecture
- React and TypeScript for the interface and timer state
- Absolute timestamps for accurate countdowns after tab throttling
- Native IndexedDB for persistent browser settings
- CSS custom properties for live themes, fonts, colors, and overlays
- Vitest and Testing Library for model, persistence, and interface tests