Dans ce tutoriel, tu vas créer un jeu d’échecs en React avec TypeScript, Vite, Tailwind et Zustand : un plateau interactif, la promotion des pions, un chronomètre configurable, plusieurs thèmes et un robot adversaire. Une architecture propre et maintenable, expliquée couche par couche et prête à accueillir le moteur Stockfish.

Niveau : intermédiaire à avancéDurée : ~3 hReact · TypeScript · ZustandCode source gratuit

Hello, aujourd’hui on va développer ensemble un jeu d’échecs web complet avec toutes les règles officielles, un robot, un chronomètre, et une interface moderne avec historique, niveau etc.

On part de zéro, on comprend chaque couche, et à la fin tu as un projet dont tu es fier. Durant mes études, j’ai été amené à développer un jeu de dames que tu peux retrouver ici, c’est sur cette base que l’idée de développer un jeu d’échecs est venue.

Comme d’habitude, tu peux télécharger le code source complet du projet disponible sur GitHub.

Ce qu’on va construire concrètement

Un jeu d’échecs jouable en 1 vs 1 local (tu peux jouer avec ton ami) ou contre la machine, une IA, avec toutes les règles (roque, en passant, promotion, pat, nulle par répétition), un chronomètre complet (Bullet, Blitz, Rapide, Classique, Fischer), 5 niveaux de difficulté pour affronter la machine, un historique des coups en notation algébrique, plusieurs thèmes visuels et tout cela avec une architecture propre et bien organisée.

Menu d'accueil du jeu d'échecs en React TypeScript avec choix du mode et du chronomètre
Démo vidéo du jeu d’échecs en React TypeScript créé dans ce tutoriel.

Voici la stack technique qu’on va utiliser :

Outil Rôle
React 18 Interface utilisateur
TypeScript 5 Typage statique
Vite Build tool ultra-rapide
Tailwind CSS Styles utilitaires
Zustand Gestion d’état
chess.js Moteur des règles d’échecs
react-chessboard Composant plateau visuel

Prérequis

Pour suivre ce tutoriel, tu dois savoir utiliser React (composants, hooks, props), comprendre les bases de TypeScript (interfaces, types, génériques) et savoir utiliser npm en ligne de commande.

Tu verras, pas besoin d’être expert. Si tu as déjà fait quelques projets React, tu es prêt.

Étape 1 : Mise en place du projet

On commence par créer le projet avec Vite, qui est aujourd’hui la meilleure option pour un projet React moderne. Crée le dossier dans lequel tu vas créer ton projet et ouvre ton invite de commandes. Voici les commandes à tapper:

npm create vite@latest echecs-pro -- --template react-ts
cd echecs-pro
npm install
terminal

On installe ensuite toutes les dépendances dont on aura besoin :

npm install chess.js react-chessboard zustand tailwind-merge clsx
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
terminal

Configurer Tailwind

Ouvre le fichier tailwind.config.js, on va dire à Tailwind où trouver nos fichiers :

export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: { extend: {} },
  plugins: [],
}
tailwind.config.js

Dans src/styles/globals.css, on importe Tailwind et on ajoute quelques styles de base :

@tailwind base;
@tailwind components;
@tailwind utilities;

* { margin: 0; padding: 0; box-sizing: border-box; }
html, body { height: 100%; width: 100%; }
src/styles/globals.css

Configurer le chemin @

Pour éviter les imports relatifs à rallonge (`../../stores/…`), on configure un alias `@` qui pointe vers `src/` :

Dans vite.config.ts :

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
  server: { port: 3000 },
})
vite.config.ts

Dans tsconfig.json :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}
tsconfig.json

Étape 2 : L’architecture du projet

Avant d’écrire du code, prenons le temps de réfléchir à l’organisation. C’est ce qui fait la différence entre un projet maintenable et euhhh, un spaghetti.

src/ ├── core/ ← logique métier pure, sans React │ ├── engine/ ← wrapper autour de chess.js │ ├── timer/ ← moteur de chronomètre │ └── stockfish/ ← gestionnaire de l’IA ├── stores/ ← état global avec Zustand ├── components/ ← composants React réutilisables │ ├── organisms/ ← composants complexes (le plateau) │ └── molecules/ ← composants composés (timer, dialog) ├── views/ ← les « pages » de l’app │ ├── Menu/ │ └── Game/ ├── utils/ ← fonctions utilitaires └── styles/ ← CSS global et thèmes

Le principe clé : la logique du jeu (règles, timer, IA) ne dépend pas de React. Elle est dans `core/`. Les stores Zustand font le lien entre la logique et l’interface. Les composants n’affichent que des données et appellent des actions.

Étape 3 : Le moteur d’échecs

Chess.js est une librairie qui implémente toutes les règles des échecs. On va créer un wrapper autour d’elle pour avoir une API propre et typée.

Les types de base

Commençons par définir nos types dans src/core/engine/types.ts:

// Les deux couleurs
export type Color = 'w' | 'b'

// Les 6 types de pièces (p=pion, n=cavalier, b=fou, r=tour, q=dame, k=roi)
export type PieceSymbol = 'p' | 'n' | 'b' | 'r' | 'q' | 'k'

// Les 64 cases de l'échiquier
export type Square =
  | 'a1' | 'b1' | 'c1' /* ... */ | 'h8'

// Un coup joué avec toutes ses métadonnées
export interface Move {
  from: Square
  to: Square
  color: Color
  piece: PieceSymbol
  captured?: PieceSymbol
  promotion?: PieceSymbol
  flags: string
  san: string   // notation courte "e4", "Nf3", "O-O"
  lan: string   // notation longue "e2e4"
  before: string
  after: string
}

// État de la partie
export type GameStatus =
  | 'playing' | 'checkmate' | 'stalemate' | 'draw'
  | 'threefold_repetition' | 'insufficient_material'

export type GameMode = 'local' | 'ai'
src/core/engine/types.ts

La classe ChessEngine

On crée maintenant src/core/engine/ChessEngine.ts. L’idée est simple : toutes les interactions avec chess.js passent par cette classe, qui garantit que nos types TypeScript sont respectés.

import { Chess } from 'chess.js'
import type { Color, GameState, Move, MoveOptions, Square } from './types'

export class ChessEngine {
  private chess: Chess

  constructor(fen?: string) {
    // Si on passe une FEN, on charge cette position. Sinon, position de départ.
    this.chess = fen ? new Chess(fen) : new Chess()
  }

  // Tente de jouer un coup — retourne null si illégal
  move(moveOptions: MoveOptions): Move | null {
    try {
      const result = this.chess.move({
        from: moveOptions.from,
        to: moveOptions.to,
        promotion: moveOptions.promotion,
      })
      if (!result) return null
      return this.convertMove(result)
    } catch {
      return null
    }
  }

  // Annule le dernier coup
  undo(): Move | null {
    const result = this.chess.undo()
    return result ? this.convertMove(result) : null
  }

  // Tous les coups légaux depuis une case (ou toute la position)
  getLegalMoves(square?: Square): Move[] {
    return this.chess
      .moves({ square, verbose: true })
      .map(m => this.convertMove(m))
  }

  // Le statut de la partie
  getGameStatus() {
    if (this.chess.isCheckmate()) return 'checkmate'
    if (this.chess.isStalemate()) return 'stalemate'
    if (this.chess.isThreefoldRepetition()) return 'threefold_repetition'
    if (this.chess.isInsufficientMaterial()) return 'insufficient_material'
    if (this.chess.isDraw()) return 'draw'
    return 'playing'
  }

  getFen() { return this.chess.fen() }
  getTurn(): Color { return this.chess.turn() as Color }
  isInCheck() { return this.chess.inCheck() }
  isGameOver() { return this.chess.isGameOver() }
  reset() { this.chess.reset() }
  clone() { return new ChessEngine(this.getFen()) }
}
src/core/engine/ChessEngine.ts

Pourquoi ce wrapper ? Chess.js retourne ses propres types internes. En les convertissant vers nos types, on garde le contrôle et on peut changer de librairie en bas niveau sans toucher au reste de l’application.

Étape 4 : La gestion d’état avec Zustand

Zustand est une librairie de gestion d’état légère et simple. Contrairement à Redux, pas de boilerplate, pas de reducers complexes. Juste un objet avec des données et des fonctions.

Pourquoi Zustand plutôt que useState ?

Parce que l’état du jeu d’échecs doit être partagé entre plusieurs composants qui ne sont pas dans la même hiérarchie : le plateau, le panneau de contrôles, l’historique, les timers. Passer tout ça en props deviendrait vite cauchemardesque. Clin d’oeil à ceux qui veulent se lancer avec useState. Le principe reste le même.

Le store principal

Dans src/stores/useGameStore.ts :

import { create } from 'zustand'
import { ChessEngine } from '@/core/engine/ChessEngine'
import type { Move, MoveOptions, Square, GameMode, Color, GameStatus } from '@/core/engine/types'

interface GameStore {
  engine: ChessEngine
  currentPosition: string  // FEN de la position actuelle
  moveHistory: Move[]
  currentMoveIndex: number
  turn: Color
  inCheck: boolean
  gameStatus: GameStatus
  selectedSquare: Square | null
  legalMovesForSelected: Square[]
  lastMove: Move | null

  makeMove: (moveOptions: MoveOptions) => boolean
  undoMove: () => boolean
  selectSquare: (square: Square | null) => void
  resetGame: () => void
  newGame: (mode: GameMode) => void
}

export const useGameStore = create<GameStore>((set, get) => ({
  engine: new ChessEngine(),
  currentPosition: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
  moveHistory: [],
  currentMoveIndex: -1,
  turn: 'w',
  inCheck: false,
  gameStatus: 'playing',
  selectedSquare: null,
  legalMovesForSelected: [],
  lastMove: null,

  makeMove: (moveOptions) => {
    const { engine } = get()
    const move = engine.move(moveOptions)
    if (!move) return false

    const state = engine.getState()
    set({
      currentPosition: state.fen,
      moveHistory: [...get().moveHistory, move],
      currentMoveIndex: get().currentMoveIndex + 1,
      turn: state.turn,
      inCheck: state.inCheck,
      gameStatus: state.status,
      selectedSquare: null,
      legalMovesForSelected: [],
      lastMove: move,
    })
    return true
  },

  selectSquare: (square) => {
    const { engine, turn } = get()
    if (!square) {
      set({ selectedSquare: null, legalMovesForSelected: [] })
      return
    }

    const piece = engine.getPiece(square)
    // On ne peut sélectionner que ses propres pièces
    if (!piece || piece.color !== turn) {
      set({ selectedSquare: null, legalMovesForSelected: [] })
      return
    }

    const legalMoves = engine.getLegalMoves(square)
    set({
      selectedSquare: square,
      legalMovesForSelected: legalMoves.map(m => m.to),
    })
  },

  // ... autres actions
}))
src/stores/useGameStore.ts

Ce qu’il faut retenir : create() prend une fonction qui reçoit `set` (pour modifier l’état) et `get` (pour lire l’état actuel). On retourne l’objet initial, avec les valeurs de départ et les actions. Propre, simple, efficace.

Étape 5 : Le chronomètre

Le système de timer est l’une des parties les plus intéressantes du projet. On doit gérer deux chronomètres indépendants, les passer d’un joueur à l’autre après chaque coup, et gérer l’incrément Fischer.

Le TimerEngine

Dans src/core/timer/TimerEngine.ts, le moteur utilise setInterval pour décompter toutes les 100ms :

export class TimerEngine {
  private intervals: Map<'w' | 'b', NodeJS.Timeout> = new Map()
  private timeRemaining: Record<'w' | 'b', number>
  private lastTickTime: number | null = null

  constructor(private config: TimeControl, private callbacks: TimerCallbacks) {
    this.timeRemaining = {
      w: config.initialTime * 1000,
      b: config.initialTime * 1000,
    }
  }

  start(color: 'w' | 'b') {
    this.stop(color)  // évite les doublons
    this.lastTickTime = Date.now()

    const interval = setInterval(() => {
      const now = Date.now()
      const elapsed = this.lastTickTime ? now - this.lastTickTime : 0
      this.lastTickTime = now

      this.timeRemaining[color] -= elapsed

      if (this.timeRemaining[color] <= 0) {
        this.timeRemaining[color] = 0
        this.stop(color)
        this.callbacks.onTimeout?.(color)
      }

      this.callbacks.onTick?.(color, this.timeRemaining[color])
    }, 100)

    this.intervals.set(color, interval)
  }

  // Passe le timer d'un joueur à l'autre (avec incrément Fischer)
  switch(from: 'w' | 'b', to: 'w' | 'b') {
    this.stop(from)
    if (this.config.increment > 0) {
      this.timeRemaining[from] += this.config.increment * 1000
    }
    this.start(to)
  }
}
src/core/timer/TimerEngine.ts

Pourquoi mesurer l’`elapsed`plutôt que de décompter 100ms fixe ? Parce que `setInterval` n’est pas garanti à exactement 100ms. En mesurant le temps réellement écoulé entre deux ticks, on évite la dérive.

Les presets de temps

On définit tous les formats classiques :

export const TIME_CONTROLS = {
  bullet:    { name: 'Bullet',    initialTime: 60,   increment: 0 },
  blitz:     { name: 'Blitz',     initialTime: 180,  increment: 2 },
  rapid:     { name: 'Rapide',    initialTime: 600,  increment: 0 },
  classical: { name: 'Classique', initialTime: 1800, increment: 0 },
  fischer:   { name: 'Fischer',   initialTime: 300,  increment: 3 },
  none:      { name: 'Sans timer',initialTime: 0,    increment: 0 },
}
TypeScript

Étape 6 : Le composant plateau

Le composant ChessBoard utilise react-chessboard pour le rendu visuel, mais gère lui-même toute la logique d’interaction.

export function ChessBoard({ boardWidth = 600, orientation = 'white' }) {
  const { currentPosition, selectedSquare, legalMovesForSelected,
          makeMove, selectSquare, turn, gameStatus, engine } = useGameStore()

  const [promotionMove, setPromotionMove] = useState(null)

  // Calcule les styles des cases : sélection en jaune, coups légaux en points
  const customSquareStyles = useMemo(() => {
    const styles = {}

    legalMovesForSelected.forEach(square => {
      styles[square] = {
        background: 'radial-gradient(circle, rgba(0,0,0,.1) 25%, transparent 25%)',
        borderRadius: '50%',
      }
    })

    if (selectedSquare) {
      styles[selectedSquare] = { backgroundColor: 'rgba(255, 255, 0, 0.4)' }
    }

    return styles
  }, [selectedSquare, legalMovesForSelected])

  const handleSquareClick = (square) => {
    // Si une case est sélectionnée et qu'on clique sur une destination légale → on joue
    if (selectedSquare && legalMovesForSelected.includes(square)) {
      if (isPromotionMove(selectedSquare, square)) {
        setPromotionMove({ from: selectedSquare, to: square })
        return
      }
      makeMove({ from: selectedSquare, to: square })
      selectSquare(null)
      return
    }
    // Sinon on sélectionne la case
    selectSquare(square)
  }

  return (
    <>
      <Chessboard
        position={currentPosition}
        onSquareClick={handleSquareClick}
        onPieceDrop={(from, to) => makeMove({ from, to })}
        boardOrientation={orientation}
        customSquareStyles={customSquareStyles}
        boardWidth={boardWidth}
        customDarkSquareStyle={{ backgroundColor: 'var(--board-dark)' }}
        customLightSquareStyle={{ backgroundColor: 'var(--board-light)' }}
      />

      {promotionMove && (
        <PromotionDialog
          color={turn}
          onSelect={(piece) => {
            makeMove({ ...promotionMove, promotion: piece })
            setPromotionMove(null)
          }}
        />
      )}
    </>
  )
}
ChessBoard.tsx

Le point délicat : la promotion. Quand un pion arrive à la dernière rangée, on doit interrompre le flux normal, afficher une fenêtre de choix, puis jouer le coup avec la pièce choisie. C’est pour ça qu’on stocke le coup en attente dans `promotionMove`.

Étape 7 : L’IA

Pour ce projet, l’IA ou le bot est volontairement simplifiée : elle joue des coups légaux aléatoires, avec une préférence pour les captures et les coups donnant échec aux niveaux élevés. C’est une excellente base pour intégrer plus tard Stockfish WebAssembly.

export class StockfishManager {
  async getBestMove(fen: string, difficulty: DifficultyConfig): Promise<string> {
    // Simule le temps de réflexion
    await new Promise(resolve => setTimeout(resolve, difficulty.movetime))

    const chess = new Chess(fen)
    const legalMoves = chess.moves({ verbose: true })

    let selectedMove

    if (difficulty.skillLevel > 10) {
      // Niveaux élevés : préférer captures et coups donnant échec
      const goodMoves = legalMoves.filter(m =>
        m.captured || m.san.includes('+') || m.san.includes('#')
      )
      selectedMove = goodMoves.length > 0
        ? goodMoves[Math.floor(Math.random() * goodMoves.length)]
        : legalMoves[Math.floor(Math.random() * legalMoves.length)]
    } else {
      // Niveaux faibles : aléatoire pur
      selectedMove = legalMoves[Math.floor(Math.random() * legalMoves.length)]
    }

    // Format UCI : "e2e4" ou "e7e8q" pour une promotion
    return selectedMove.from + selectedMove.to + (selectedMove.promotion || '')
  }
}
StockfishManager.ts

Le format UCI (Universal Chess Interface) est le standard de communication avec les moteurs d’échecs. Un coup est exprimé comme ` »case_départ » + « case_arrivée »`, avec la lettre de promotion collée à la fin pour les pions (ex: ` »e7e8q »` = promotion en dame).

Étape 8 : Le système de thèmes

On utilise des variables CSS pour les couleurs, ce qui permet de changer de thème sans toucher au JavaScript. On définit 5 thèmes dans `src/styles/themes.css` :

/* Thème par défaut */
:root {
  --board-light: #f0d9b5;
  --board-dark: #b58863;
  --accent-primary: #769656;
  --bg-primary: #312e2b;
  --text-primary: #ffffff;
}

/* Thème sombre */
[data-theme='dark'] {
  --board-light: #779952;
  --board-dark: #4e6b3d;
  --accent-primary: #88c0d0;
  --bg-primary: #2e3440;
  --text-primary: #eceff4;
}
src/styles/themes.css

Pour changer de thème : `document.documentElement.setAttribute(‘data-theme’, ‘dark’)`

C’est tout. Tailwind utilise ces variables directement dans les classes custom, comme `bg-[var(–bg-primary)]` ou via l’extension de config.

Étape 9 : Assembler la vue principale

La vue GameView orchestre tout : elle abonne les composants aux stores, gère les effets de bord (lancement de l’IA, gestion du timer), et affiche la mise en page en trois colonnes.

export function GameView({ onBackToMenu }) {
  const { moveHistory, turn, gameStatus, mode, makeMove, engine } = useGameStore()
  const { isInitialized, isThinking, requestMove, initialize } = useStockfishStore()
  const { preset, start: startTimer, switchTimer, stop: stopTimer } = useTimerStore()

  // Synchronise le timer avec les coups joués
  useEffect(() => {
    if (moveHistory.length === 1) {
      startTimer('b')  // les blancs ont joué le 1er coup, on démarre le timer des noirs
    } else if (moveHistory.length > previousCount) {
      switchTimer(previousTurn, turn)
    }
  }, [moveHistory.length])

  // Lance l'IA quand c'est son tour
  useEffect(() => {
    if (mode === 'ai' && turn === 'b' && isInitialized && !isThinking) {
      setTimeout(() => {
        requestMove(engine.getFen()).then(uciMove => {
          const from = uciMove.substring(0, 2)
          const to = uciMove.substring(2, 4)
          const promotion = uciMove[4]
          makeMove({ from, to, promotion })
        })
      }, 300)
    }
  }, [turn, isInitialized, isThinking])

  return (
    <div className="flex h-full">
      {/* Panneau gauche : contrôles + historique */}
      {/* Centre : plateau */}
      {/* Panneau droit : timers + infos */}
    </div>
  )
}
GameView.tsx

Étape 10 : Build et déploiement

Une fois le projet prêt :

# Vérifier qu'il n'y a pas d'erreurs TypeScript
npx tsc --noEmit

# Construire pour la production
npm run build
terminal
Partie en cours dans le jeu d'échecs en React TypeScript avec robot et chronomètre

Le dossier `dist/` contient les fichiers statiques à déployer. Tu peux les héberger sur n’importe quel serveur (Nginx, Apache) ou sur des plateformes comme Vercel, Netlify ou GitHub Pages.

Pour aller plus loin

Ce projet est une base solide. Voici quelques pistes d’amélioration que tu peux explorer :

Intégrer le vrai Stockfish: La librairie `stockfish.js` permet d’utiliser le moteur Stockfish compilé en WebAssembly directement dans le navigateur. Remplace la classe `StockfishManager` par une vraie communication UCI via `postMessage`.

Sons: La librairie `Howler.js` est déjà dans les dépendances. Ajoute des sons de déplacement de pièces, d’échec, et de promotion.

Persistance: Utilise `Dexie` (déjà installé) pour sauvegarder l’historique des parties dans IndexedDB.

Export PGN: La méthode `engine.getPgn()` est déjà là. Ajoute un bouton « Exporter » qui génère un fichier `.pgn` téléchargeable.

Sélecteur de thème: Ajoute des boutons dans les paramètres pour changer de thème en un clic via `document.documentElement.setAttribute(‘data-theme’, …)`.

Conclusion

Tu as maintenant un jeu d’échecs complet et professionnel. Ce projet démontre plusieurs concepts importants du développement web moderne : l’architecture en couches, la gestion d’état avec Zustand, les hooks React pour les effets de bord, le typage strict avec TypeScript, et le système de thèmes avec CSS variables.

Le code source complet est disponible sur GitHub. Clone-le, explorez-le, modifie-le. On se retrouve dans les commentaires pour toutes questions.

Pour aller plus loin

FAQ : questions fréquentes

Faut-il bien connaître React pour suivre ce tutoriel ?

Il faut connaître les bases : composants, hooks et props, ainsi que les types et interfaces TypeScript. Chaque couche de l’architecture est ensuite expliquée en détail.

Le robot utilise-t-il Stockfish ?

Pas encore : le robot est volontairement simplifié. Il joue des coups légaux aléatoires, en privilégiant les prises et les échecs aux niveaux élevés. La classe StockfishManager est prévue pour brancher ensuite le vrai moteur Stockfish en WebAssembly.

Pourquoi utiliser Zustand plutôt que Redux ?

Zustand offre un état global avec beaucoup moins de code. Pour un jeu comme celui-ci, il est plus simple à mettre en place et tout aussi performant.

Comment mettre le jeu en ligne ?

Lance npm run build pour générer le dossier dist, puis héberge-le gratuitement sur Vercel, Netlify ou GitHub Pages.

2 Comments

  1. Josie

    Bonjour, votre site est intéress je voudrais apprendre à développé aussi pourquoi vous ne faites pas pour débutant

    • Bonjour,

      La plupart des tutoriels sont destinés à des personnes ayant déjà quelques bases. Je peux vous conseiller de vous tourer vers le site d’OpenClassroom, c’est franchophone et les cours sont adaptés.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *