Skip to main content

My Chess Board Was Waiting on a 7.3 MB Engine It Didn't Need Yet

Updated 4 min readMarkdown

I built Zugzwang, a chess puzzle app that runs Stockfish in the browser as WASM. On a throttled 4G connection, the board took 38.7 seconds to show up.

The cause was my own wiring. The app waited for Stockfish to finish loading before it drew the puzzle. Stockfish is 7.3 MB, and nobody needs it to look at a puzzle. They need it after their first move.

So I stopped making the board wait. Board-visible time, the first moment the board element has a non-zero size on the page, dropped from 38.7s to 3.7s (p50).

The board was waiting on the engine

This is the load before the fix. The puzzle JSON arrives in about 1.4s. Then everything waits on the engine download.

Before: board visibility blocked on Stockfish WASM (36.28s)

Draw the board first, load the engine alongside

I split startup into two tracks that don't wait on each other:

  • Fetch the puzzle and render the board as soon as it arrives.
  • Load Stockfish in the background.

After: board visible at 3.7s. The striped bar is Stockfish, still downloading when the board appears.

The puzzle panel shows "Loading engine..." only if you make a move before the engine is ready. Until then you see the board and think about the position.

Metric Before (p50) After (p50) Change
Board visible 38,669 ms 3,673 ms −90.5%
LCP 38,688 ms 4,488 ms −88.4%
FCP 2,376 ms 2,268 ms −4.5%

What it costs

The engine doesn't arrive any sooner. It's the same 7.3 MB download. If you move fast, you wait on "Loading engine..." instead of a blank screen. I haven't measured how often that happens yet.

If the engine reports an error, the app checks moves against the puzzle's stored solution line instead. You lose engine analysis for alternative lines, but you can still solve the puzzle.

Two smaller cleanups

Before the Stockfish change I made two smaller ones. They cut bytes, not seconds. FCP moved only 108 ms across all three changes.

The menu (stats, settings, theme pickers) was in the main bundle even though most people don't open it right away. I moved it behind React.lazy() so it loads on first open. Initial JS went from 427.6 kB to 415.2 kB.

Every board theme and piece set shipped as CSS on first load, though you only ever see one. Now the default theme ships in the initial CSS and the others load when you pick them:

const boardThemeLoaders: Record<string, () => Promise<unknown>> = {
  blue:  () => import("@/styles/chessground-board-theme-blue.css"),
  brown: () => import("@/styles/chessground-board-theme-brown.css"),
  // ...
};

Initial CSS went from 159.5 kB to 81.2 kB (33.0 kB to 12.9 kB gzipped).

What didn't help

SSR could pre-render the board's HTML, but Stockfish still downloads and starts on the client. It doesn't touch the 7.3 MB.

WASM streaming was already on. Stockfish's runtime uses instantiateStreaming, and forcing it off changed engine readiness by about 35 ms.

How I measured

7 cold loads per version, with Playwright driving Chromium, a fresh browser context, and the cache disabled. The network was throttled through CDP to 1.6 Mbps down, 0.75 Mbps up, and 750 ms RTT. Board-visible comes from a MutationObserver watching for .ui-board-root with a non-zero size. LCP and FCP come from PerformanceObserver. Runs were tight: the slowest was within 20 ms of the median on every metric.

The lesson

The 7.3 MB engine was never render-blocking by nature. I had wired it up that way. The download is the same size it always was. The board just stopped waiting for it.

Next I'll try a service worker to cache the WASM for repeat visits, which this post doesn't measure.

Source: github.com/sanjitsaluja/zugzwang-puzzle-trainer

No comments yet. Be the first to comment.