NOSSLETTER.techLIVE
back to archive

sea: generate a compile cache for the VFS modules

Language: JavaScript+908 -71feature
concepts demonstrated
Build-time compilationVirtual file system (VFS)Module caching and serializationNode.js embedding and runtime flags
The Issue & Context

Previously, enabling both useCodeCache and useVfs flags was rejected because SEA's compile cache was only generated and consumed for embedder compile paths, not for modules loaded through the VFS runtime loaders, leaving VFS bundles without a useful startup cache.

Root Cause Analysis

The SEA compile cache was integrated only on embedder-specific compile paths (compileFunctionForCJSLoader with is_sea_main=true and the kEmbedder branch), while VFS modules loaded via standard CJS/ESM loaders bypassed this caching layer, so no cache was generated or consumed for them.

Solution Strategy & Architectural Pattern

This PR adds a build-time step that launches a Node.js instance to mount the VFS assets and compiles every module file without execution, using a portable CompileCacheHandler keyed relative to the mount point. The resulting compile cache entries are serialized and embedded as reserved node:sea:compile-cache assets, enabling cache consumption for VFS modules at runtime in a follow-up PR.

Key Takeaway for Contributors

When caching code in complex module loading scenarios, ensure that compile caches cover all loading paths by simulating runtime environments at build time to precompile and cache every module, rather than relying on main script-only or embedder-specific caches.