Skip to main content
This guide covers the fundamental operations in chessops: creating positions, making moves, and playing through a simple game.

​
Creating a Position

Chessops provides multiple ways to create chess positions.

​
Starting Position

import { Chess } from 'chessops/chess';

// Create the starting position
const pos = Chess.default();
console.log(pos.turn); // 'white'
console.log(pos.fullmoves); // 1

​
Making Moves

Moves can be created using square indices, UCI notation, or SAN notation.
1

Understanding Square Indices

Squares are represented as numbers 0-63, where 0 is a1, 7 is h1, 56 is a8, and 63 is h8.
import { parseSquare, makeSquare } from 'chessops';

// Convert square names to indices
const e2 = parseSquare('e2'); // 12
const e4 = parseSquare('e4'); // 28

// Convert indices back to names
const square = makeSquare(12); // 'e2'
2

Creating Moves

import { Chess } from 'chessops/chess';

const pos = Chess.default();

// Move from e2 to e4 (indices 12 to 28)
const move = { from: 12, to: 28 };
pos.play(move);
3

Handling Promotions

import { Chess } from 'chessops/chess';
import { parseFen } from 'chessops/fen';
import { parseSan } from 'chessops/san';

// Position with pawn ready to promote
const setup = parseFen('4k3/P7/8/8/8/8/8/4K3 w - - 0 1').unwrap();
const pos = Chess.fromSetup(setup).unwrap();

// Promote to queen
const move = parseSan(pos, 'a8=Q')!;
pos.play(move);

// Or using square indices
const queenPromotion = { from: 48, to: 56, promotion: 'queen' as const };

​
Playing a Complete Game

Here’s how to play through the famous “Fool’s Mate” - the shortest possible checkmate. 
import { Chess } from 'chessops/chess';
import { parseSan } from 'chessops/san';
import { makeFen } from 'chessops/fen';

// Start a new game
const pos = Chess.default();

// Play the moves
const moves = ['f3', 'e5', 'g4', 'Qh4#'];

for (const san of moves) {
  const move = parseSan(pos, san);
  if (!move) {
    console.error(`Invalid move: ${san}`);
    break;
  }
  
  console.log(`Playing: ${san}`);
  pos.play(move);
  
  // Check game state after each move
  if (pos.isCheck()) {
    console.log('Check!');
  }
  if (pos.isCheckmate()) {
    console.log('Checkmate!');
    break;
  }
}

// Final position
console.log(pos.isCheckmate()); // true
console.log(makeFen(pos.toSetup()));
// Output: rnb1kbnr/pppp1ppp/8/4p3/6Pq/5P2/PPPPP2P/RNBQKBNR w KQkq - 1 3

​
Cloning Positions

Always clone a position before making moves if you want to preserve the original. 
import { Chess } from 'chessops/chess';
import { parseUci } from 'chessops';

const original = Chess.default();

// Try different moves without affecting the original
const withE4 = original.clone();
withE4.play(parseUci('e2e4')!);

const withD4 = original.clone();
withD4.play(parseUci('d2d4')!);

// Original position is unchanged
console.log(original.fullmoves); // 1

​
Converting Positions

Convert positions to various formats for storage or display. 
import { Chess } from 'chessops/chess';
import { makeFen } from 'chessops/fen';
import { parseUci } from 'chessops';

const pos = Chess.default();
pos.play(parseUci('e2e4')!);

const fen = makeFen(pos.toSetup());
console.log(fen);
// Output: rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1

​
Error Handling

Chessops uses the Result type for operations that can fail. Always unwrap results properly. 
import { Chess } from 'chessops/chess';
import { parseFen } from 'chessops/fen';

// Invalid FEN
const result = parseFen('invalid fen string');

if (result.isOk) {
  const setup = result.value;
  // Use setup
} else {
  console.error('Failed to parse FEN:', result.error);
}

// Or use unwrap() if you're certain it will succeed
const setup = parseFen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1').unwrap();

// Creating a position from invalid setup
const posResult = Chess.fromSetup(setup);
if (posResult.isOk) {
  const pos = posResult.value;
  // Use position
} else {
  console.error('Invalid position:', posResult.error);
}

​
Next Steps

Move Generation

Learn how to generate and validate legal moves

Position Analysis

Analyze positions for checks, checkmate, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us