Module 17 — Distribution & Cold Starts: Single Executable Applications & V8 Snapshots

How Snapshots Work

Build time:
  1. Run initialization code (import modules, set up schemas, etc.)
  2. V8 serializes the current heap state to a binary blob
  3. The blob is embedded in the SEA binary
 
Runtime:
  1. V8 deserializes the pre-built heap (microseconds)
  2. Your request handler runs immediately
  3. All pre-initialized objects are available without re-execution

Creating a Startup Snapshot

// snapshot-entry.js — runs at BUILD TIME to initialize the heap
import { setDeserializeMainFunction } from 'v8';
import { compileFunction } from 'node:vm';
 
// Initialize expensive resources at BUILD TIME
import Ajv from 'ajv';
const ajv = new Ajv({ allErrors: true });
 
// Pre-compile all schemas at build time
import transactionSchema from './schemas/transaction.json' with { type: 'json' };
import paymentSchema from './schemas/payment.json' with { type: 'json' };
const validateTransaction = ajv.compile(transactionSchema);
const validatePayment = ajv.compile(paymentSchema);
 
// This function runs at RUNTIME when the snapshot is deserialized
setDeserializeMainFunction(async () => {
  // validateTransaction and validatePayment are already compiled —
  // available immediately from the deserialized heap
  const { default: Fastify } = await import('fastify');
  const fastify = Fastify({ logger: true });
 
  fastify.post('/api/v2/payments', async (request, reply) => {
    // Uses pre-compiled validator from snapshot — no compilation at request time
    if (!validatePayment(request.body)) {
      return reply.code(400).send({ errors: validatePayment.errors });
    }
    return await processPayment(request.body);
  });
 
  await fastify.listen({ port: 3000 });
});

# Build the snapshot
node --snapshot-blob snapshot.blob --build-snapshot snapshot-entry.js
 
# Run with snapshot (skips all initialization)
node --snapshot-blob snapshot.blob
# Application ready in <10ms instead of 400ms

What Can and Cannot Be Snapshotted

Can be snapshotted (serializable V8 heap objects):

• Compiled ajv validator functions
• Pre-parsed JSON schemas and configurations
• Lookup tables and pre-computed maps
• Module-level initialized classes

Cannot be snapshotted:

• File descriptors (TCP sockets, file handles) — OS resources don't survive serialization
• Promises in progress — async state cannot be serialized
• Native addon instances — C++ objects outside V8 heap
• Crypto keys created at runtime — security-sensitive, not serializable

---

SEA + Snapshot: The Complete Pipeline

For a blockchain indexer, combine both techniques:

// build-snapshot.js — runs at build time
import { setDeserializeMainFunction } from 'v8';
import Ajv from 'ajv';
import blockSchema from './schemas/block.json' with { type: 'json' };
import txSchema from './schemas/transaction.json' with { type: 'json' };
 
// Compile validators AT BUILD TIME
const ajv = new Ajv({ allErrors: true });
const validateBlock = ajv.compile(blockSchema);
const validateTransaction = ajv.compile(txSchema);
 
// Pre-build route Radix tree for Fastify
import Fastify from 'fastify';
const fastify = Fastify({ logger: false });
 
// Register routes at build time — Radix tree built once
fastify.post('/api/v1/ingest', { schema: { body: txSchema } }, txHandler);
fastify.post('/api/v1/blocks', { schema: { body: blockSchema } }, blockHandler);
 
setDeserializeMainFunction(async () => {
  // At startup: validators ready, routes compiled, Radix tree built
  // Connect to database (cannot snapshot TCP connections)
  await pool.connect();
  await fastify.listen({ port: 3000 });
  console.log('Ready in < 20ms');
});

Traditional startup timeline:
  0ms   → Node.js runtime starts
  50ms  → Import Fastify, Ajv, pg, kafkajs...
  150ms → Compile JSON schemas
  250ms → Build Radix tree from route definitions
  320ms → Connect to database
  400ms → Server ready
 
With SEA + snapshot:
  0ms  → Deserialize snapshot (V8 heap, compiled validators, Radix tree)
  15ms → Connect to database (not snapshotted)
  20ms → Server ready

The Real Mechanism: useSnapshot and useCodeCache in sea-config.json

The pipeline above shows the two techniques conceptually glued together, but Node.js actually wires snapshot generation directly into the SEA build itself — you don't run a separate node --build-snapshot step and then inject a second blob. sea-config.json takes two boolean fields that control this:

{
  "main": "build-snapshot.js",
  "output": "sea-prep.blob",
  "disableExperimentalSEAWarning": true,
  "useSnapshot": true,      // build "main" as a V8 startup snapshot, not a plain script
  "useCodeCache": false,    // mutually exclusive in practice with useSnapshot — see gotchas below
  "assets": {
    "schema.json": "dist/schema.json"
  }
}

When useSnapshot: true, node --experimental-sea-config sea-config.json runs main as the snapshot-building entry point (it must call setDeserializeMainFunction, exactly like build-snapshot.js above) and embeds the resulting snapshot directly into the generated blob — one build step produces a SEA binary that deserializes its heap on startup, instead of hand-rolling --build-snapshot and postject separately.

Gotcha — import() breaks under useCodeCache: true. The example above uses await import('fastify') inside setDeserializeMainFunction. If you instead set "useCodeCache": true (V8 bytecode caching, a lighter-weight alternative to a full snapshot), dynamic import() calls inside the SEA's main script do not work — the code cache mechanism does not support the dynamic module graph resolution import() requires at runtime. If your entry point uses dynamic import() anywhere, useCodeCache is not compatible with it; stick to static import at the top of the file, or use useSnapshot instead.

Gotcha — cross-platform builds require both flags false. For the blockchain node operator use case above, operators run a mix of Linux servers and macOS/Windows dev machines. Both V8 snapshots and V8 code caches are tied to the exact V8 build and CPU architecture they were generated on — you cannot generate a snapshot on macOS/arm64 and have it deserialize correctly inside a Linux/x64 binary. If your CI builds a Linux binary on a macOS runner (or any cross-compilation scenario), set both "useSnapshot": false and "useCodeCache": false in sea-config.json for that build target. You lose the cold-start win for cross-compiled binaries; the alternative is building natively on a matching-architecture runner per target platform.

A Lighter-Weight Alternative: NODE_COMPILE_CACHE

Not every service needs a full SEA. Node.js 22 added NODE_COMPILE_CACHE, an environment variable that persists V8's compiled bytecode to a directory on disk across process restarts — no SEA build, no snapshot entry point, no sea-config.json:

# Point Node at a directory to persist compile cache between runs
export NODE_COMPILE_CACHE=/var/cache/node-compile-cache
node dist/app.js

// Or enable it programmatically (Node 22.8+)
const { enableCompileCache } = require('node:module');
enableCompileCache('/var/cache/node-compile-cache');

The first run compiles normally and writes bytecode to the cache directory; subsequent runs skip V8's parse/compile step for unchanged files. It doesn't eliminate module loading time the way a snapshot does — require/import resolution and top-level module code still execute — but it's a one-line change with none of the SEA build pipeline's complexity, and it composes with regular node dist/app.js deployments where a full SEA binary is overkill.

---

Summary

Next: Crossing the Boundary: Rust, N-API, and WASI for Cryptographic Throughput →

---