A fast, minimal, local-first typing speed test.

---

Table of Contents

• About
• Features
• Screenshots
• Demo
• Tech Stack
• Project Structure
• Getting Started
• Roadmap
• Contributing
• Deployment
• License
• Author
• Support
• Star History

---

About

KeyFlow is a typing speed test built for people who want to practice without friction. There is no account to create, no server storing your results, and no clutter between you and the keyboard. Every setting and every result lives entirely in your browser.

It exists because most typing test sites have accumulated years of ads, trackers, and unrelated features on top of a simple idea: type text, measure how well you did. KeyFlow strips that back down.

It is built for touch typists practicing speed and accuracy, developers who want a distraction-free daily warm-up, and anyone who wants a typing test they can read the source code of.

Back to top

Features

Typing

• Time Mode — 15, 30, 60, or 120 second sessions
• Word Mode — 10, 25, 50, or 100 word sessions
• Quote Mode — short, medium, or long quotes
• Zen Mode — untimed, endless practice with no target

Statistics

• Words per minute (WPM) and raw WPM
• Accuracy
• Consistency
• Mistake count
• Character count, broken down by correct, incorrect, and extra

Customization

• Twelve color themes
• Fourteen typing fonts across monospace and sans-serif
• Light, dark, and system appearance modes
• Keyboard sounds, including a real mechanical switch recording set
• An animated on-screen virtual keyboard

Open Source

• MIT licensed
• Open to community contributions
• Structured issue templates for bugs and feature requests
• Public roadmap

Back to top

Screenshots

Homepage assets/screenshots/home.png	Typing Screen assets/screenshots/test.png
Settings assets/screenshots/settings.png	Results assets/screenshots/results.png
Dark Theme assets/screenshots/dark-theme.png	Light Theme assets/screenshots/light-theme.png

Screenshot files are not yet included in this repository. See assets/screenshots/README.md for the exact filenames expected above.

Back to top

Demo

A short screen recording of a typing session belongs at assets/demo.gif. Not included yet — see assets/screenshots/README.md.

Back to top

Tech Stack

• Next.js — React framework, App Router
• React
• TypeScript
• Tailwind CSS
• Framer Motion — animation
• Browser localStorage — the only persistence layer; no database, no backend

Back to top

Project Structure

keyflow/
├── app/
│   ├── page.tsx               # Home page — the typing experience itself
│   ├── results/page.tsx       # Results page
│   ├── layout.tsx             # Root layout: fonts, providers
│   └── globals.css            # Design tokens and global styles
├── components/
│   ├── typing/                # Typing engine UI: words, caret, keyboard, controls
│   ├── results/                # Stat cards, WPM chart, results summary
│   ├── settings/                 # Settings panel, theme and font pickers
│   ├── layout/                     # Top bar, logo
│   ├── providers/                    # Theme and settings context providers
│   └── ui/                             # Shared primitives: button, card, sheet, tabs
├── hooks/
│   ├── use-typing-engine.ts   # Core typing and scoring state machine
│   ├── use-keyboard-sound.ts  # Sound engine (sprite and sample based)
│   ├── use-focus-mode.ts      # Idle and focus-mode timing
│   └── use-key-tracker.ts     # Physical key state for the virtual keyboard
├── lib/                        # Word lists, quotes, stats math, storage, themes, fonts
├── types/                       # Shared TypeScript types
├── public/sounds/                # Keyboard sound assets
└── assets/                        # README screenshots and demo GIF (this repo, not the app)

Back to top

Getting Started

Prerequisites

• Node.js 18.18 or later
• npm (or your package manager of choice)

Clone

git clone https://github.com/PawanChoudhary0607/KeyFlow.git
cd KeyFlow

Install

npm install

Configure (optional)

cp .env.example .env.local
# set NEXT_PUBLIC_GITHUB_URL to your fork's URL if you're publishing your own copy

Run

npm run dev

Open http://localhost:3000.

Build

npm run build
npm run start

Deploy

See Deployment.

Back to top

Roadmap

Current version: v1.0.0

Planned for future releases:

• Achievements
• User profiles
• Multiplayer typing races
• Typing history and progress tracking
• Custom theme builder
• Additional sound packs
• Performance analytics
• Plugin system

See CHANGELOG.md for what has already shipped, and open issues for discussion on any of the above.

Back to top

Contributing

Contributions are welcome. The general workflow:

1. Fork the repository
2. Create a branch (git checkout -b feat/short-description)
3. Commit your changes (git commit -m "feat: add short description")
4. Push to your fork (git push origin feat/short-description)
5. Open a pull request against main

Please read CONTRIBUTING.md for coding conventions and CODE_OF_CONDUCT.md before contributing.

Back to top

Deployment

KeyFlow is a standard Next.js application and deploys to Vercel with no additional configuration:

1. Push this repository to GitHub
2. Import it in the Vercel dashboard
3. Set the NEXT_PUBLIC_GITHUB_URL environment variable if you want the in-app GitHub button to point at your fork
4. Deploy

Any other Node.js hosting platform that supports Next.js (npm run build followed by npm run start) works as well.

Back to top

License

Distributed under the MIT License. See LICENSE for details.

The Mechanical sound pack includes third-party audio used under the Apache License 2.0 — see THIRD_PARTY_NOTICES.md.

Back to top

Author

Pawan Choudhary

• GitHub: PawanChoudhary0607
• LinkedIn: Pawan Choudhary
• Portfolio:Pawan Choudhary

Back to top

Support

If KeyFlow is useful to you, consider leaving a star. It helps the project reach more people and is a quick way to show support.

Back to top

Star History

Back to top