Modern, fully client-side chess application built with React + TypeScript + Vite, powered by the custom engine @rumenx/chess.
- Legal move generation & game state via `@rumenx/chess`
- Move history with time-travel (jump to any ply)
- AI opponent with multiple difficulty tiers (random → depth 5 minimax w/ alpha-beta & capture ordering)
- Hint system (on-demand best move preview)
- Under-promotion support (choose promotion piece)
- Board orientation flip & side selection
- Time controls (e.g. 3+2, 5+0, 10+5, unlimited) with increments & flag detection
- Player naming (persistent) and configurable vs AI / local 2-player mode
- Persistent UI preferences (orientation, difficulty, coordinates, debug flags)
- Debug overlays (piece color & mapping diagnostics) via collapsible Developer panel
- Copy FEN / PGN export
- Responsive board sizing with CSS `clamp()`
- Modular SCSS design system
| Label | Strategy | Nominal Depth |
|---|---|---|
| Harmless | random legal move | 0 |
| Easy | minimax | 1 |
| Medium | minimax + ordering | 2 |
| Hard | minimax + ordering | 3 |
| Expert | alpha-beta + capture ordering | 4 |
| Godlike | optimized alpha-beta (throttled) | 5 |
The engine dynamically reduces depth in pathological or large branching scenarios to keep UI responsive.
Time format is `M+I` (minutes base + seconds increment). Unlimited mode disables the clocks. When a side reaches 0 the opponent wins on time; result string (`1-0` / `0-1`) reflects the flag event.
```bash git clone https://github.com/RumenDamyanov/react-chess.git cd react-chess npm install npm run dev ```
Then open: http://localhost:5173
```text src/ App.tsx # Composition + settings + clocks hooks/ useChessGame.ts # Core game + clocks + history logic ... (future: useGameArchive.ts) services/ChessAI.ts # AI difficulty + search components/ChessBoard/ # Board + Square rendering components/MoveHistory # Move list & navigation utils/ # PGN, persistence helpers styles/ # SCSS tokens & theming tests/ # Jest tests (planned) ```
| Script | Purpose |
|---|---|
| `npm run dev` | Start Vite dev server (HMR) |
| `npm run build` | Production build |
| `npm run preview` | Preview production build |
| `npm run format` | Format code with Prettier |
| `npm run format:check` | Check code formatting |
| `npm run lint` | ESLint checks |
| `npm run type-check` | Run TypeScript in isolated mode |
| `npm test` | Run Jest test suite |
| `npm run test:watch` | Run tests in watch mode |
| `npm run test:coverage` | Generate coverage report |
Comprehensive test coverage for core functionality:
- 61 passing tests covering services and utilities
- 85%+ coverage on ChessAI service (difficulty levels, move selection, minimax)
- 77%+ coverage on ChessEngine wrapper (initialization, moves, game state)
- 50%+ coverage on chess notation utilities (SAN formatting, move chunking)
Run tests locally:
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Generate coverage report| Module | Statements | Branches | Functions | Lines |
|---|---|---|---|---|
| ChessAI | 93% | 73% | 90% | 93% |
| ChessEngine | 77% | 77% | 68% | 77% |
| chessNotation | 51% | 51% | 33% | 57% |
PRs welcome! Before submitting:
- Run
npm run format:check- ensure code is properly formatted - Run
npm run lint- pass all linting checks - Run
npm run type-check- no TypeScript errors - Run
npm test- all tests must pass with coverage - Keep UI changes accessible (labels, aria-live where needed)
See the full Contributing Guide for detailed guidelines.
- Opening explorer / book weighting
- Engine benchmarking panel
- Dark theme toggle
- Cloud sync (optional)
- React + TypeScript + Vite
- Custom chess engine: `@rumenx/chess`
- SCSS modules (design tokens & utilities)
Explore other libraries and tools from the same developer:
- @rumenx/chess - TypeScript chess engine with legal move generation (npm)
- @rumenx/chatbot - AI chatbot integration library (npm)
- @rumenx/seo - SEO analysis and optimization toolkit (npm)
- @rumenx/sitemap - Dynamic sitemap generator (npm)
- @rumenx/feed - RSS/Atom feed generator (npm)
- php-chatbot - PHP chatbot framework (Packagist)
- php-geolocation - Geolocation services library (Packagist)
- php-seo - PHP SEO toolkit (Packagist)
- php-sitemap - Sitemap generation (Packagist)
- php-feed - Feed generation (Packagist)
- go.rumenx.com/chess - Go chess engine (go.rumenx.com/chess)
- go.rumenx.com/chatbot - Go chatbot framework (go.rumenx.com/chatbot)
- Code of Conduct - Community guidelines and expectations
- Contributing Guide - How to contribute to the project
- Security Policy - Responsible disclosure and security practices
- License - Open source license details
MIT © Rumen Damyanov
- Documentation: This README and linked governance docs
- Issues: GitHub Issues
- Email: contact@rumenx.com
Have an idea or spot a bug? Open an issue or propose a PR!