A modern TypeScript/JavaScript interface for the Stockfish chess engine, compiled to WebAssembly for maximum performance.

• 🚀 Modern async/await API - No more callbacks
• 📦 ES Module support - Works with modern bundlers (Webpack, Vite, Rollup)
• 🔧 Full TypeScript support - Complete type definitions included
• ⚡ WebAssembly powered - Maximum performance using Stockfish 17.1
• 🌐 Universal - Works in Node.js and browsers
• 🎯 Simple API - Get started with just a few lines of code

npm install stockfish

import { getAiMove } from 'stockfish';

// Get the best move from the starting position
const move = await getAiMove(
  'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
  [], // no moves played yet
  { depth: 12 }
);

console.log(`Best move: ${move.move}`);
console.log(`Evaluation: ${move.score} centipawns`);

import { createEngine } from 'stockfish';

// Create and configure an engine instance
const engine = await createEngine({
  threads: 4,
  hashSize: 128
});

// Listen to search progress
engine.on('info', (info) => {
  console.log(`Depth ${info.depth}: ${info.score}cp`);
});

// Set a position
await engine.setPosition({
  fen: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
  moves: ['e2e4', 'e7e5']
});

// Search for the best move
const move = await engine.getAiMove({
  depth: 15,
  time: 5000  // 5 second maximum
});

console.log(`Best move: ${move.move} (${move.score}cp)`);

// Clean up
await engine.quit();

Quick way to get the best move for a position.

• fen: string - Position in FEN notation
• moves?: string[] - Array of moves in UCI notation
• options?: SearchOptions - Search configuration

Returns: Promise<MoveInfo>

Create a new engine instance for advanced usage.

• options?: StockfishEngineOptions - Engine configuration

Returns: Promise<StockfishEngine>

interface MoveInfo {
  move: string;        // Best move in UCI notation
  ponder?: string;     // Move to ponder on
  score?: number;      // Evaluation in centipawns
  depth?: number;      // Search depth reached
  nodes?: number;      // Nodes searched
  nps?: number;        // Nodes per second
  time?: number;       // Time taken in milliseconds
  pv?: string[];       // Principal variation
}

interface SearchOptions {
  depth?: number;           // Maximum search depth
  time?: number;            // Maximum search time (ms)
  nodes?: number;           // Maximum nodes to search
  searchMoves?: string[];   // Limit search to these moves
  multiPV?: number;         // Number of principal variations
  infinite?: boolean;       // Infinite search (must stop manually)
}

interface StockfishEngineOptions {
  threads?: number;         // Number of threads (1-32)
  hashSize?: number;        // Hash table size in MB
  initTimeout?: number;     // Engine initialization timeout
  options?: Record<string, string | number | boolean>; // UCI options
}

Set the current board position.

Get the best move for the current position.

Get static evaluation of the current position.

Stop the current search.

Terminate the engine and clean up resources.

The engine emits the following events:

• ready - Engine is initialized and ready
• info - Search progress information
• data - Raw engine output
• quit - Engine has been terminated

Run the included examples:

# Quick test
npm run example:quick

# Advanced example
npm run example:modern

git clone https://github.com/nmrugg/stockfish.js
cd stockfish.js
npm install
npm run build
npm test

For testing the package locally before publishing:

# Create a local npm package (.tgz file)
npm run pack:local

# Create and verify the package works correctly
npm run pack:verify

# Install the package globally for testing
npm run pack:test

# Clean up generated package files
npm run pack:clean

The pack:verify script creates a temporary test environment, installs the local package, and verifies that all exports work correctly.

This package is designed to work seamlessly with modern JavaScript bundlers:

• ✅ Webpack 5+ - Full support with proper ES module handling
• ✅ Vite - Native ES module support
• ✅ Rollup - Works with @rollup/plugin-node-resolve
• ✅ Parcel - Automatic ES module detection
• ✅ esbuild - Fast builds with ES module support

• Chrome 87+
• Firefox 84+
• Safari 14+
• Edge 88+

Requires WebAssembly and SharedArrayBuffer support.

• Node.js 16+ (for stable ES module support)
• Requires --experimental-wasm-threads --experimental-wasm-simd flags for Node.js 14-18

1. Reuse Engine Instances - Create one engine and reuse it for multiple positions
2. Adjust Hash Size - Larger hash tables improve search quality (default: 16MB)
3. Use Multiple Threads - Set threads option for faster searches on multi-core systems
4. Time Limits - Use time option instead of depth for consistent performance
5. Stop Long Searches - Use engine.stop() to interrupt long calculations

GPL-3.0 (same as original Stockfish)

Based on Stockfish chess engine.

Contributions are welcome! Please read the contributing guidelines and submit pull requests to the main repository.