Library / SDK
jhlywa/chess.js avatar
jhlywa/chess.js

chess.js move generation and PGN parsing, without the engine

A TypeScript chess library for chess move generation/validation, piece placement/movement, and check/checkmate/draw detection

4,457 stars993 forksTypeScriptBSD-2-Clause

At a glance

What is it?
chess.js is a TypeScript rules library: it generates legal moves, validates them, and reads and writes PGN, but it never chooses a move. That boundary decides who can use it and who has to pair it with something else.
Who is it for?
Adopt chess.js when a React board, a puzzle checker or a PGN pipeline needs a correct rules core in the same language as the interface. Skip it when you need move choice, opening knowledge or a strength rating, because the package ships none of those and a separate UCI engine becomes a second process with its own protocol.
Can I use it commercially?
Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 96 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • jhlywa/chess.js4,457 ★ · +47
Star history
Repository2026-09-232026-11-15
jhlywa/chess.js4.4k4.5k

47 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One Chess object holds the whole position

A chess.js game is a single mutable object holding an entire position. Instantiating Chess gives you a game from the standard starting array, and every call moves that object forward or reads it back. Nothing is global, so two independent games can sit in the same process without interfering, which matters for a site that shows a puzzle board beside a review board.

The repository description states the scope bluntly: move generation, validation, execution and game state, "everything but the AI". Board rendering is not included either. Your component decides how to draw the squares; the library only decides which moves were legal. The split is why the package can sit inside a React component tree without dragging a view layer along, and why you end up writing the piece components yourself.

moves() hands back SAN strings, so every move is a parse

The core API is a two step loop and it is worth understanding what crosses the boundary. moves() returns an array of moves in standard algebraic notation, and move() takes one of those strings and executes it. The README example picks a random entry and plays it until the game ends.

ts
import { Chess } from 'chess.js'

const chess = new Chess()

while (!chess.isGameOver()) {
  const moves = chess.moves()
  const move = moves[Math.floor(Math.random() * moves.length)]
  chess.move(move)
}
console.log(chess.pgn())

The README example only passes these SAN strings around; the rest of the API is covered on the documentation site rather than in the README.

npm install chess.js, then call isGameOver() before you touch moves()

Installation is a single command from the npm registry, and the import in the example above is the whole setup. There is no configuration file, no schema to migrate and no global state to initialise.

bash
npm install chess.js

Start with a terminal condition check rather than a board. The README loop guards with isGameOver() at the top of each pass, and any UI that advances a move by button or drag should hold the same guard, since checkmate and stalemate both close the move list at once.

The published entry points are fixed by the manifest: main points at dist/cjs/chess.js for CommonJS, module at dist/esm/chess.js for bundlers, and types at dist/types/chess.d.ts. A bundler will pick the ESM build on its own.

The PGN parser is generated from a peggy grammar before TypeScript runs

PGN text is not handled by hand written string splitting. The build script runs peggy with peggy.config.mjs to generate the parser, then type checks, then bundles with rollup. The clean script deletes src/pgn.js and src/pgn.d.ts by hand, which tells you those two files are build products rather than sources, and that the grammar file is the real input.

That matters if you fork the library. Editing the parser means editing the peggy grammar and regenerating, not editing a JavaScript file that will be overwritten. It also means the parser's behaviour is fixed at build time by a grammar, so move comment and variation handling follows whatever the grammar accepts, and the README does not enumerate which PGN extensions are covered.

The manifest also pins a floor: engines requires node 20.0.0 or newer. Anything older is unsupported by the package's own declaration, even though a browser bundle does not run node at all.

npm run check compares the built API against a committed report

Maintenance of the public surface is enforced by tooling. The check script runs format:check, then lint, then the vitest suite, then the build, then api-extractor in verbose mode. api-extractor reads the generated declarations in dist/types/chess.d.ts and diffs them against a report tracked through api-extractor.json, so a change that alters a method signature or a return type fails the script even when the tests still pass.

The counterpart script, api:update, reruns the build and rewrites that report locally. The build is therefore not a free step: rollup output, the generated parser and the declaration files all have to agree before anything publishes, and the prepare hook runs that build automatically when the package is installed from a git URL.

The license is BSD 2-Clause, permissive for commercial use without a copyleft obligation to publish derived source. The last push landed on 2026-08-11, so the repository is not archived, yet the published version still predates that work and no release cadence is documented.

A rules library cannot tell you which move is good

This is the failure mode that trips people up, and it is a design boundary rather than a bug. chess.js will happily enumerate forty legal replies to a bad move, all of them legal, none of them advisable. isGameOver() answers a yes or no question about termination, not a question about quality.

The README example makes the point by picking at random. That loop is a correct way to produce a legal, terminated game and a valid PGN string, which is useful for testing a board, but a human watching it sees nonsense. Anything that presents itself as a playing partner needs a separate decision layer.

The obvious pairing is a UCI engine such as Stockfish, run as a separate process. That is a different architecture in every respect: the engine owns search and evaluation, speaks a line based text protocol, and returns bestmove, while chess.js stays in process and synchronous inside your JavaScript. You would keep the library for legality checking and use the engine only for choosing.

When a position arrives from outside, parse errors surface as thrown exceptions

Malformed PGN or FEN input is the common runtime failure in an app that imports real game data. Treat construction from text as untrusted input and handle the failure rather than assume a clean position.

The alternative to trusting the input is to validate upstream: strip tags, cap game length, and reject anything the grammar will not take before it reaches the constructor. None of this is documented in the README, which covers installation and one example and defers the rest to the hosted documentation site, so the tag and error surface has to be read from the API reference or from the peggy grammar itself.

Editorial conclusion

Adopt chess.js when a React board, a puzzle checker or a PGN pipeline needs a correct rules core in the same language as the interface. Skip it when you need move choice, opening knowledge or a strength rating, because the package ships none of those and a separate UCI engine becomes a second process with its own protocol. Forking it also means owning the peggy grammar and the rollup build yourself. Before wiring it into a product, verify the SAN round trip: call moves(), pass one string straight back through move(), and confirm the resulting position and move history match what your board component expects.

Frequently asked questions

Is there a CDN for chess.js?

The README gives no CDN instructions. It only points at the npm package chess.js and its install command, and it defers full documentation to https://jhlywa.github.io/chess.js.

how to install chess js

The documented install path is a single npm command that pulls the most recent published version from NPM. The package manifest additionally requires node 20.0.0 or newer.

what is chess js

It is a TypeScript library for chess move generation, validation, piece placement and movement, and check, checkmate and stalemate detection. The repository description puts it plainly as everything but the AI.

how to use chess js

Instantiate Chess, call moves() to get the legal moves in standard algebraic notation, and pass one of those strings to move(). Check isGameOver() before each move, as the README loop does, and chess.pgn() returns the game record.

Official sources

  1. jhlywa/chess.js on GitHub
  2. License: BSD-2-Clause
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/jhlywa-chess-js.svg)](https://hysenlabs.com/projects/jhlywa-chess-js)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/jhlywa-chess-js.svg)](https://hysenlabs.com/projects/jhlywa-chess-js)

Was this useful?