Skip to main content

​
Quick start

This guide will walk you through the basics of using chessops to work with chess positions and moves.

​
Basic workflow

1

Install chessops

Install the package using npm, yarn, or pnpm:
npm install chessops
2

Create a chess position

Import the necessary modules and create a position from FEN notation:
import { Chess } from 'chessops/chess';
import { parseFen } from 'chessops/fen';

// Parse a FEN string to create a Setup
const setup = parseFen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1').unwrap();

// Create a Chess position from the setup
const pos = Chess.fromSetup(setup).unwrap();
The .unwrap() method extracts the value from a Result type. In production code, you should handle errors appropriately.
3

Generate and make moves

Use the position to generate legal moves and play them:
import { parseSquare } from 'chessops';

// Get all legal moves
const moves = pos.allDests();
console.log(`${moves.size} legal destinations available`);

// Get legal moves from a specific square (e4)
const e2 = parseSquare('e2')!;
const movesFromE2 = pos.dests(e2);

// Make a move (e2-e4)
const e4 = parseSquare('e4')!;
pos.play({ from: e2, to: e4 });
4

Check position status

Query the position to check game state:
// Check if position is checkmate
if (pos.isCheckmate()) {
  console.log('Checkmate!');
}

// Check if position is in check
if (pos.isCheck()) {
  console.log('Check!');
}

// Get the outcome if game is over
const outcome = pos.outcome();
if (outcome) {
  console.log('Game over. Winner:', outcome.winner || 'Draw');
}

​
Complete example

Here’s a complete example that demonstrates parsing FEN, making moves, and checking for checkmate: 
import { Chess } from 'chessops/chess';
import { parseFen, makeFen } from 'chessops/fen';
import { parseSquare } from 'chessops';
import { parseSan, makeSan } from 'chessops/san';

// Parse Scholar's Mate position (4 moves before mate)
const fenString = 'r1bqkbnr/ppp2Qpp/2np4/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4';
const setup = parseFen(fenString).unwrap();
const pos = Chess.fromSetup(setup).unwrap();

// Check position status
console.log('Is checkmate?', pos.isCheckmate()); // true
console.log('Is check?', pos.isCheck()); // true

const outcome = pos.outcome();
if (outcome) {
  console.log('Winner:', outcome.winner); // 'white'
}

// Working with the starting position
const startSetup = parseFen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1').unwrap();
const startPos = Chess.fromSetup(startSetup).unwrap();

// Parse and play moves in SAN notation
const move1 = parseSan(startPos, 'e4');
if (move1) {
  const sanNotation = makeSan(startPos, move1);
  console.log('Playing:', sanNotation); // 'e4'
  startPos.play(move1);
}

// Get current FEN
const currentFen = makeFen(startPos.toSetup());
console.log('Current position:', currentFen);
Chessops uses bitboards internally for efficient position representation and move generation. The SquareSet class provides methods for working with sets of squares.

​
Working with PGN

Chessops includes a powerful PGN parser for reading chess games: 
import { parsePgn, startingPosition } from 'chessops/pgn';
import { parseSan } from 'chessops/san';

const pgn = '1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 *';
const games = parsePgn(pgn);

for (const game of games) {
  const pos = startingPosition(game.headers).unwrap();
  
  for (const node of game.moves.mainline()) {
    const move = parseSan(pos, node.san);
    if (!move) break; // Illegal move
    pos.play(move);
  }
  
  console.log('Final position reached');
}

​
Using chess variants

Chessops supports 8 different chess variants: 
import { Crazyhouse, Atomic, Antichess, KingOfTheHill } from 'chessops/variant';
import { parseFen } from 'chessops/fen';

// Create a Crazyhouse position
const setup = parseFen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1').unwrap();
const crazyhousePos = Crazyhouse.fromSetup(setup).unwrap();

// Atomic chess
const atomicPos = Atomic.fromSetup(setup).unwrap();

// Each variant has its own rules for move generation and game end conditions

​
Next steps

Now that you understand the basics, explore more advanced features:

Attack calculations

Learn about attack and ray calculations

Board transformations

Mirror and rotate positions

Streaming PGN parser

Process large PGN files efficiently

Full API reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us