Chess Opening Explorer

Live at openingbook.xyz

A chess learning platform for exploring and practising openings: 12,377 opening positions in 31 families, with AI-written strategic content, win rates from Lichess, curated YouTube videos and Lichess studies, and a move trainer.

Features

Discover (the landing page)

• Search: server-side search with popularity-weighted ranking, backed by a small client-side index for instant name matching. Also understands ECO codes, move sequences and style words such as "aggressive gambit".
• Browse: filter openings by level, style and family, and sort them.
• Paste a game: paste any PGN to identify the opening it reached.
• Repertoire: star openings to keep a saved list (its own tab on mobile).

Opening pages

• Board and move tree: step through the main line, with links to the opening's parent lines and its most-played continuations.
• Practice mode: a move trainer with hints and feedback, played as either colour.
• Win rates: live statistics by rating band from the Lichess opening explorer, falling back to a snapshot from the Lichess rated-games database. Both cover all rated players, not master games.
• Plans: AI-written descriptions, strategic themes and common plans.
• Videos and studies: YouTube videos from 16 trusted channels and Lichess study chapters, matched to the position. A page with none of its own shows its opening family's best, labelled as such.

Analyse (your own games)

• Import your rated games from Chess.com or Lichess and see your results grouped by opening and family, as White and as Black, with strengths and weaknesses. Two sample reports show the result before you type a username.

Quick Start

npm install   # all workspace dependencies, and the git hooks
npm run dev   # API on 3010 + frontend on 3000

• Frontend: http://localhost:3000
• API: http://localhost:3010

Requires Node.js 22 or newer (CI runs Node 24). The opening data is committed in api/data/, so no download step is needed, and no environment variables are needed to run the app locally. They are only required for the data pipelines and live Lichess stats.

Environment variables

Create a .env in the repo root. Every variable is optional; each unlocks a specific feature.

Variable	Needed for
LICHESS_EXPLORER_TOKEN	Live win rates via the /api/explorer proxy
YOUTUBE_API_KEY	Video pipeline (full mode and metadata enrichment)
JEV_API_KEY	Video pipeline's relevance filter (see below)
GOOGLE_AI_API_KEY	LLM enrichment via Gemini
GOOGLE_APPLICATION_CREDENTIALS_JSON	Vertex AI service-account credentials
VERTEX_AI_PROJECT_ID	Vertex AI project
VERTEX_AI_LOCATION	Vertex AI region

LICHESS_EXPLORER_TOKEN is a zero-scope Lichess personal access token. Lichess has required authentication on the opening explorer since March 2026; without the token the proxy returns 503 and the win-rate panel falls back to snapshot statistics. It must also be set in the Vercel project environment for production.

JEV_API_KEY comes from console.typesafe.ai. Without it the video pipeline still applies cached answers but leaves new videos unfiltered.

Project Structure

chess-opening-explorer/
├── packages/
│   ├── api/              # Express API: business logic, source of truth
│   ├── web/              # React 19 + TypeScript frontend (Vite)
│   └── shared/           # Shared utilities and types
├── api/                  # Vercel serverless wrappers (thin, import packages/api)
├── api/data/             # Canonical generated data consumed by the API
├── middleware.ts         # Vercel edge middleware: pre-renders opening pages
├── config/               # Pipeline configuration (channels, matcher, pins)
├── data/                 # Source data, including the opening families
├── design-system/        # Warm Editorial Dark reference bundle
├── docs/                 # Proposals, reviews, backlog
├── scripts/              # Build, SEO, audit and data-maintenance scripts
├── tools/
│   ├── analysis/         # Python: Lichess popularity pipeline
│   ├── course-discovery/ # Node: Lichess study import pipeline
│   ├── family-taxonomy/  # Node: assigns every position to a family
│   ├── llm-enrichment/   # Node: AI content generation
│   ├── sample-reports/   # Node: the Analyse page's sample reports
│   └── video-pipeline/   # Node: YouTube video discovery and matching
├── tests/                # Backend tests (Jest) + Playwright e2e
└── .github/memory-bank/  # Project context and current state

Testing

npm run test:all        # backend + frontend: the check that matters
npm run test:backend    # Jest
npm run test:frontend   # Vitest
npm run test:e2e        # Playwright end-to-end
npm run test:coverage   # backend coverage
npm run build           # type errors surface here, not in the test suites

Jest collects from tests/** and tools/**/tests/**. packages/*/tests/ is in testPathIgnorePatterns, so a Jest test placed inside a package silently never runs. Put backend tests in the root tests/ directory. Frontend tests live beside their components in packages/web/src/**/__tests__/.

Coverage reports: coverage/lcov-report/index.html (backend), packages/web/coverage/index.html (frontend).

Git hooks

Husky installs these on npm install:

• pre-commit: Prettier formats staged files; ESLint checks staged files in packages/ and blocks the commit on errors
• pre-push: type-check, then the full backend and frontend suites

This is the beginning of the README. Read the rest at the original. Read the full README ↗