Skip to content

AGENTS.md

Latest commit

 

History

History
42 lines (29 loc) · 2.05 KB

AGENTS.md

File metadata and controls

42 lines (29 loc) · 2.05 KB

This package loads V8 snapshots created by @tooling/v8-snapshot into Electron applications to accelerate startup time by providing pre-initialized module exports and definitions without hitting the file system.

Key Commands

# Build TypeScript to dist/
yarn workspace @packages/v8-snapshot-require build

# Run a specific test file
yarn workspace @packages/v8-snapshot-require test -- <path-to-spec>

# Run tests matching a glob pattern
yarn workspace @packages/v8-snapshot-require test -- "<glob-pattern>"

# Type-check
yarn workspace @packages/v8-snapshot-require check-ts

Architecture

  • src/snapshot-require.ts — Main entry; hooks into @packages/packherd-require to serve modules from the V8 snapshot instead of the file system
  • src/dependency-map.ts — Constructs and consults the resolver map (module key lookup without file system access)
  • src/utils.ts — Helper utilities for path normalization and key derivation
  • src/constants.ts — Shared constants (separator strings, env vars)
  • src/types.ts — TypeScript types for snapshot structures

Gotchas / Notes

  • The resolver map key format is <dir>***<request> mapping to the fully resolved path relative to the project base dir; keys are embedded in the snapshot itself.
  • Enable debug logging with DEBUG=cypress:pack* or DEBUG=cypress:snap* to inspect hit/miss rates (exportHits, definitionHits, misses).
  • exports (fully initialized) and definitions (lazy initializer functions) overlap in the snapshot; a module can appear in both.
  • To disable the snapshot entirely (for debugging), set DISABLE_SNAPSHOT_REQUIRE=1.

Integration Points

  • Works in concert with @packages/packherd-require for the actual module resolution and loading logic.
  • The snapshot itself is generated by @tooling/v8-snapshot during the build pipeline and embedded into the Electron app.
  • @packages/server uses hook-require.js and v8-snapshot-entry.js to install the snapshot require hook at startup.

Auto-Generated Files

  • dist/ — Generated by tsc; do not edit by hand.