Chess.js is a TypeScript chess library used for chess move generation/validation, piece placement/movement, and check/checkmate/stalemate detection - basically everything but the AI. It provides a complete chess engine with support for all standard chess rules, FEN and PGN formats, and comprehensive game analysis capabilities.
npm install chess.jsimport { Chess, Move, validateFen } from "chess.js";
import { WHITE, BLACK, PAWN, KING, QUEEN, ROOK, BISHOP, KNIGHT } from "chess.js";
import { DEFAULT_POSITION, SQUARES, SEVEN_TAG_ROSTER } from "chess.js";For CommonJS:
const { Chess, Move, validateFen } = require("chess.js");
const { WHITE, BLACK, PAWN, KING, QUEEN, ROOK, BISHOP, KNIGHT } = require("chess.js");import { Chess } from "chess.js";
// Create a new chess game
const chess = new Chess();
// Play a random game
while (!chess.isGameOver()) {
const moves = chess.moves();
const move = moves[Math.floor(Math.random() * moves.length)];
chess.move(move);
}
// Get the game result
console.log(chess.pgn());
console.log(`Game over: ${chess.isCheckmate() ? 'Checkmate' : 'Draw'}`);Chess.js is built around several key components:
Core chess game functionality for creating, managing, and analyzing chess positions and games.
class Chess {
constructor(fen?: string, options?: { skipValidation?: boolean });
reset(): void;
clear(options?: { preserveHeaders?: boolean }): void;
load(fen: string, options?: LoadOptions): void;
fen(options?: { forceEnpassantSquare?: boolean }): string;
}
interface LoadOptions {
skipValidation?: boolean;
preserveHeaders?: boolean;
}Move generation, validation, and execution with support for standard and advanced chess notation.
class Chess {
moves(options?: MovesOptions): string[] | Move[];
move(move: string | MoveInput, options?: { strict?: boolean }): Move;
undo(): Move | null;
}
interface MovesOptions {
verbose?: boolean;
square?: Square;
piece?: PieceSymbol;
}
interface MoveInput {
from: string;
to: string;
promotion?: string;
}Board state access, piece manipulation, and visual representation methods.
class Chess {
board(): (PieceInfo | null)[][];
get(square: Square): Piece | undefined;
put(piece: Piece, square: Square): boolean;
remove(square: Square): Piece | undefined;
findPiece(piece: Piece): Square[];
ascii(): string;
}
interface PieceInfo {
square: Square;
type: PieceSymbol;
color: Color;
}
interface Piece {
type: PieceSymbol;
color: Color;
}Position analysis including check/mate detection, draw conditions, and attack analysis.
class Chess {
isCheck(): boolean;
isCheckmate(): boolean;
isStalemate(): boolean;
isDraw(): boolean;
isGameOver(): boolean;
isAttacked(square: Square, attackedBy: Color): boolean;
attackers(square: Square, attackedBy?: Color): Square[];
}Complete Forsyth-Edwards Notation support for position serialization and validation.
function validateFen(fen: string): FenValidationResult;
interface FenValidationResult {
ok: boolean;
error?: string;
}Random number generation utility for chess position hashing and analysis.
/**
* Creates a xoroshiro128** pseudo-random number generator
* @param state - Initial 128-bit state as bigint
* @returns Generator function that returns bigint values
*/
function xoroshiro128(state: bigint): () => bigint;Portable Game Notation import/export with headers, comments, and move annotation support.
class Chess {
pgn(options?: PgnOptions): string;
loadPgn(pgn: string, options?: LoadPgnOptions): void;
setHeader(key: string, value: string): Record<string, string>;
getHeaders(): Record<string, string>;
}
interface PgnOptions {
newline?: string;
maxWidth?: number;
}
interface LoadPgnOptions {
strict?: boolean;
newlineChar?: string;
}// Basic Types
type Color = 'w' | 'b';
type PieceSymbol = 'p' | 'n' | 'b' | 'r' | 'q' | 'k';
type Square = 'a8' | 'b8' | 'c8' | 'd8' | 'e8' | 'f8' | 'g8' | 'h8' |
'a7' | 'b7' | 'c7' | 'd7' | 'e7' | 'f7' | 'g7' | 'h7' |
'a6' | 'b6' | 'c6' | 'd6' | 'e6' | 'f6' | 'g6' | 'h6' |
'a5' | 'b5' | 'c5' | 'd5' | 'e5' | 'f5' | 'g5' | 'h5' |
'a4' | 'b4' | 'c4' | 'd4' | 'e4' | 'f4' | 'g4' | 'h4' |
'a3' | 'b3' | 'c3' | 'd3' | 'e3' | 'f3' | 'g3' | 'h3' |
'a2' | 'b2' | 'c2' | 'd2' | 'e2' | 'f2' | 'g2' | 'h2' |
'a1' | 'b1' | 'c1' | 'd1' | 'e1' | 'f1' | 'g1' | 'h1';
// Constants
const WHITE = 'w';
const BLACK = 'b';
const PAWN = 'p';
const KNIGHT = 'n';
const BISHOP = 'b';
const ROOK = 'r';
const QUEEN = 'q';
const KING = 'k';
const DEFAULT_POSITION = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
const SQUARES: Square[] = [
'a8', 'b8', 'c8', 'd8', 'e8', 'f8', 'g8', 'h8',
'a7', 'b7', 'c7', 'd7', 'e7', 'f7', 'g7', 'h7',
'a6', 'b6', 'c6', 'd6', 'e6', 'f6', 'g6', 'h6',
'a5', 'b5', 'c5', 'd5', 'e5', 'f5', 'g5', 'h5',
'a4', 'b4', 'c4', 'd4', 'e4', 'f4', 'g4', 'h4',
'a3', 'b3', 'c3', 'd3', 'e3', 'f3', 'g3', 'h3',
'a2', 'b2', 'c2', 'd2', 'e2', 'f2', 'g2', 'h2',
'a1', 'b1', 'c1', 'd1', 'e1', 'f1', 'g1', 'h1'
];
const SEVEN_TAG_ROSTER: Record<string, string> = {
Event: '?',
Site: '?',
Date: '????.??.??',
Round: '?',
White: '?',
Black: '?',
Result: '*'
};