Heuristic:Cypress io Cypress V8 Snapshot Memory
| Knowledge Sources | |
|---|---|
| Domains | Build_Optimization, Performance |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
V8 snapshot generation and binary build processes require 8-16 GB of Node.js heap memory, configured via `--max-old-space-size`. Without this, builds will OOM crash.
Description
The Cypress binary build pipeline uses V8 snapshots to dramatically improve startup time. The snapshot generation process loads the entire Cypress application into memory and serializes the V8 heap. This process is extremely memory-intensive, requiring `NODE_OPTIONS=--max_old_space_size=8192` for binary builds and up to `--max-old-space-size=16384` (16 GB) for the snapshot script generator. TypeScript type-checking in CI also requires elevated memory (`--max_old_space_size=4096`).
Usage
Apply this heuristic when building the Cypress binary from source, generating V8 snapshots, running binary packaging, or debugging OOM crashes during CI builds. If a build step crashes with a JavaScript heap out of memory error, increasing the heap size is the first step.
The Insight (Rule of Thumb)
- Action: Set `NODE_OPTIONS=--max_old_space_size=8192` for binary build and package commands. Set `--max-old-space-size=16384` for V8 snapshot generation.
- Value: 8 GB for builds, 16 GB for snapshot generation, 4 GB for type-checking
- Trade-off: Requires machines with at least 16 GB RAM for full binary builds; CI runners must be appropriately sized
Reasoning
The V8 snapshot process loads the entire Cypress application module graph into a single V8 isolate and serializes it. This includes all dependencies from the packages directory. The serialized snapshot enables near-instant startup by skipping module resolution and parsing at runtime. The trade-off is a very memory-intensive build step.
Code Evidence
Binary build memory from `package.json:7`:
"binary-build": "cross-env NODE_OPTIONS=--max_old_space_size=8192 node ./scripts/binary.js build"
Binary package memory from `package.json:11`:
"binary-package": "cross-env NODE_OPTIONS=--max_old_space_size=8192 node ./scripts/binary.js package"
V8 snapshot memory from `package.json:19-20`:
"build-v8-snapshot-dev": "node --max-old-space-size=8192 tooling/v8-snapshot/scripts/setup-v8-snapshot-in-cypress.js --env=dev",
"build-v8-snapshot-prod": "node --max-old-space-size=8192 tooling/v8-snapshot/scripts/setup-v8-snapshot-in-cypress.js"
Snapshot script generator from `tooling/v8-snapshot/src/generator/create-snapshot-script.ts:276`:
NODE_OPTIONS: '--max-old-space-size=16384',
CI type-check memory from `.circleci/src/pipeline/@pipeline.yml:1541`:
command: NODE_OPTIONS=--max_old_space_size=4096 yarn check-ts --concurrency=1