Skip to content

Setup

Jump to bottom
BilgeGates edited this page May 23, 2026 · 1 revision

Setup

This page describes how to install, run, and build ChessVision against the v5.5.3 stable release on the master branch.

Prerequisites

Requirement Version
Node.js 20.x or later
pnpm 9.x or later (the lockfile is produced by pnpm 10)
Git Any recent version

The repository uses pnpm as its package manager. npm and yarn are not supported and will produce a different lockfile than the one checked into master.

Cloning the Stable Branch

git clone https://github.com/BilgeGates/chess-vision.git
cd chess-vision
git checkout master

Installing Dependencies

pnpm install

The install step also runs husky install through the prepare script. This wires up the pre-commit and commit-message hooks. If you are checking the repository out in a CI environment, set HUSKY=0 to skip hook installation.

Development Server

pnpm dev

Vite serves the application on port 3000. Hot module replacement is enabled by default. The dev server is for local use only.

Production Build

pnpm build

The build emits to dist/. esbuild is used as the minifier. Vendor chunks are configured manually in vite.config.js:

  • vendor-react
  • vendor-icons
  • vendor-motion
  • vendor-dnd
  • vendor-virtualization

Assets below assetsInlineLimit: 4096 are inlined; larger assets, including the chess piece SVGs, remain HTTP-cacheable.

To preview the production build locally:

pnpm preview

Quality Gates

Three commands form the standard pre-merge check:

pnpm test                 # FEN parser unit tests via node --test
pnpm lint                 # ESLint with --max-warnings=0 in production
pnpm format:check         # Prettier check (no writes)

The test runner uses native node --test against src/utils/fenParser.test.js. No experimental Node flags are required on the v5.x line.

Bundle Analysis

pnpm build:analyze

This builds with vite-bundle-visualizer and opens an interactive bundle treemap. There is no automated bundle-size regression tracking in CI on the v5.x line.

Repository Layout

chess-vision/
├── src/
│   ├── components/
│   │   ├── board/          # Pure display components
│   │   ├── features/       # Feature panels (ColorPicker, Export, Fen, History, etc.)
│   │   ├── interactions/   # Drag-and-drop layer
│   │   ├── layout/         # Navbar, app shell
│   │   └── ui/             # Reusable primitives (Button, Modal, Input)
│   ├── contexts/           # FENBatchContext, LayoutContext, ThemeSettingsContext
│   ├── hooks/              # useFENHistory, useTheme, useNotifications, ...
│   ├── pages/              # Lazy-loaded routes
│   ├── routes/Router.jsx   # Route table with AnimatePresence
│   ├── utils/              # FEN, canvas, export, validation, logger, ...
│   ├── constants/          # Static data
│   └── assets/             # Piece SVGs and static assets
├── docs/                   # Architecture, CHANGELOG, FAQ, accessibility, etc.
├── .github/                # Issue templates, workflows, dependabot config
├── ROADMAP.md              # Faithful v5.5.3 snapshot of master
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md

Path Aliases

The Vite and TypeScript configurations expose a single alias on the v5.x line:

@/*  →  src/*

Imports inside the source tree should use this alias rather than relative paths that traverse multiple directories.

Clone this wiki locally