Startup: snapshots & code caching

The startup problem

Loading performance already showed that JavaScript costs download, parse, compile, and execution. This expert lesson starts one layer earlier: before your app code runs, the engine and host must create a usable JavaScript world with built-ins such as Object, Array, Math, RegExp, Promise, and often Intl. Doing that from scratch for every page, worker, isolate, or Node process would waste startup time.

This lesson goes deeper than Loading performance did. That lesson introduced HTTP caching and V8 code caching from a product-performance angle. Here you will model the engine rules, prove Node behavior, and connect the topic back to lazy parsing, bytecode and interpreters, Meet the engines, service workers, and runtimes.

V8's Custom startup snapshots post explains the core trick: initialize a context once, serialize that prepared heap into a snapshot blob, embed or provide that blob to the engine, then deserialize it for new isolates or contexts. The post's 2015 numbers are worth treating as historical evidence rather than current promises: on one desktop, context creation dropped from about 40 ms to less than 2 ms; on an average mobile phone, from about 270 ms to 10 ms.

Think of the startup snapshot as the engine's baseline pantry. It can contain built-in objects, maps, strings, functions, and embedder-provided initialization code. It does not make your application execute for free; after deserialization, your script still runs and may still parse, compile, allocate, fetch, hydrate, and call APIs.

1const eagerBuiltins = ["Object", "Array", "Promise"];Run2const lazyBuiltins = ["Math.max", "Intl.NumberFormat", "RegExp.prototype.exec"];3 4function createContextFromSnapshot(pageNeedsIntl) {5  const heap = { source: "startup-snapshot", ready: [...eagerBuiltins] };6  const lazyQueue = [...lazyBuiltins];7  const touchedBuiltin = pageNeedsIntl ? "Intl.NumberFormat" : "Math.max";8 9  const index = lazyQueue.indexOf(touchedBuiltin);10  if (index !== -1) lazyQueue.splice(index, 1);11  heap.ready.push(touchedBuiltin);12 13  return {14    heapSource: heap.source,15    eagerCount: eagerBuiltins.length,16    remainingLazy: lazyQueue.length,17    touchedBuiltin,18  };19}20 21const boot = createContextFromSnapshot(false);22console.log(boot.heapSource);23console.log(boot.touchedBuiltin);24console.log(boot.remainingLazy);

1const eagerBuiltins = ["Object", "Array", "Promise"];2const lazyBuiltins = ["Math.max", "Intl.NumberFormat", "RegExp.prototype.exec"];3 4function createContextFromSnapshot(pageNeedsIntl) {5  const heap = { source: "startup-snapshot", ready: [...eagerBuiltins] };6  const lazyQueue = [...lazyBuiltins];7  const touchedBuiltin = pageNeedsIntl ? "Intl.NumberFormat" : "Math.max";8 9  const index = lazyQueue.indexOf(touchedBuiltin);10  if (index !== -1) lazyQueue.splice(index, 1);11  heap.ready.push(touchedBuiltin);12 13  return {14    heapSource: heap.source,15    eagerCount: eagerBuiltins.length,16    remainingLazy: lazyQueue.length,17    touchedBuiltin,18  };19}20 21const boot = createContextFromSnapshot(false);22console.log(boot.heapSource);23console.log(boot.touchedBuiltin);24console.log(boot.remainingLazy);

The walkthrough is a teaching model, not V8 source. It captures the important relationship: a new context can start from a prepared heap, then touch only the built-ins the page actually uses. The same page behavior must be observable whether the engine rebuilt the heap slowly or deserialized it quickly.

Snapshots save startup time, but copying everything eagerly can waste memory. V8's Lazy deserialization post says V8 v6.4 enabled lazy deserialization by default in 2018, reducing V8 heap memory by more than 500 KB per Chrome tab on average. The same post reported that popular sites used only about 30% of built-in functions on average, with some using only 16%.

The mechanism is concrete: built-in code objects live at known positions in a dedicated snapshot area. A lazy placeholder points to the DeserializeLazy built-in. On the first call, V8 finds the relevant code object, deserializes it, and installs it on the function so later calls go directly to normal code. Each built-in function and bytecode handler is deserialized at most once per isolate.

Lazy deserialization is a good reminder for application code: do not eagerly import and run every optional feature at startup. Engines are already careful about built-ins; your app should be careful about route code, editors, charting libraries, locales, and admin-only tools.

Node exposes V8 startup snapshots to user-land. In Node 22.23.1, this lesson verified both the command-line flags and the v8.startupSnapshot API. A tiny real run produced: Node 22.23.1 and StartupPerformance:build-snapshot when launched from a snapshot blob.

1node --snapshot-blob snap.blob --build-snapshot entry.js2node --snapshot-blob snap.blob main.js

1globalThis.lessonSnapshot = {2  title: "StartupPerformance",3  compiledAt: "build-snapshot",4};

1console.log("Node " + process.versions.node);2console.log(3  globalThis.lessonSnapshot.title + ":" +4  globalThis.lessonSnapshot.compiledAt,5);

Node's V8 docs show a second shape: the build script can register callbacks. Use addSerializeCallback to compact or release serializable state before the blob is written. Use setDeserializeMainFunction when the snapshot itself should provide the process entry point instead of a separate main.js file.

1const v8 = require("node:v8");2 3const state = { words: ["snapshot", "cache"] };4 5v8.startupSnapshot.addSerializeCallback((data) => {6  data.words.push("serialized");7}, state);8 9v8.startupSnapshot.setDeserializeMainFunction((data) => {10  console.log(data.words.join(","));11}, state);

Code caching is different from a startup snapshot. After compiling a script, an engine can serialize compilation metadata, then later consume that data with the same source. V8's Code caching for JavaScript developers post says Chrome has two levels for classic and module scripts: a best-effort in-memory isolate cache keyed by source code, and a serialized on-disk cache managed by Chrome and associated with the script URL in the HTTP resource cache.

As of September 2026, this lesson still treats those V8 posts as public guidance, not a guaranteed browser contract. The numbers you should quote carefully are from the posts: Chrome 66's improved code caching reported a 20–40% reduction in parse and compilation time on many pages, and the developer post documented a 1 KiB source-size threshold. Heuristics can change, so production work should measure real traces rather than depend on a magic threshold.

1import vm from "node:vm";2 3const source = "function add(a, b) { return a + b; } add(2, 3);";4const first = new vm.Script(source, { produceCachedData: true });5const cachedData = first.cachedData ?? first.createCachedData();6 7const accepted = new vm.Script(source, { cachedData });8console.log(accepted.cachedDataRejected);9 10const changed = new vm.Script(source + " console.log('changed');", { cachedData });11console.log(changed.cachedDataRejected);

The Node test for this lesson uses the real node:vm API. It proves that cached data is accepted for the identical source (cachedDataRejected === false) and rejected when extra source is appended (true). Timing is deliberately not asserted; cache correctness is the observable fact.

1import { enableCompileCache } from "node:module";2 3const result = enableCompileCache("./.node-compile-cache");4console.log(result.status);5console.log(result.directory.endsWith(".node-compile-cache"));

Node 22.23.1 also exposes module.enableCompileCache() and the NODE_COMPILE_CACHE=dir environment variable. Node's docs say this persists V8 code cache for CommonJS and ES modules in a directory, may slow the first module-graph load, and can speed subsequent loads when module contents do not change.

The model below encodes the rules just described: stable URL and source, a 1 KiB minimum, a cold/warm/hot sequence, source invalidation, URL invalidation, and a recent-visit window. It is intentionally small enough to audit line by line, then flexible enough to play with.

1const rules = { minimumSourceBytes: 1024, recentVisitHours: 72 };Run2const largeSource = "console.log('dashboard shell');\n" +3  "export const route = 'dashboard';\n".repeat(44);4const changedSource = largeSource + "export const build = 'v2';\n";5const tinySource = "console.log('tiny');";6 7function decideEngineCacheLoads(loads) {8  const entries = new Map();9 10  return loads.map((load) => {11    const sizeBytes = load.content.length;12    const previous = entries.get(load.url);13    const changed = previous ? previous.content !== load.content : false;14    const stale = previous ? load.hour - previous.lastSeenHour > rules.recentVisitHours : false;15 16    if (sizeBytes < rules.minimumSourceBytes) {17      return { outcome: "too-small", usesCachedBytecode: false };18    }19 20    if (!previous || changed || stale) {21      entries.set(load.url, {22        content: load.content,23        hits: 1,24        lastSeenHour: load.hour,25        hasDiskCodeCache: false,26      });27      return { outcome: "cold", usesCachedBytecode: false };28    }29 30    previous.hits += 1;31    previous.lastSeenHour = load.hour;32 33    if (!previous.hasDiskCodeCache) {34      previous.hasDiskCodeCache = true;35      return { outcome: "warm", usesCachedBytecode: false };36    }37 38    return { outcome: "hot", usesCachedBytecode: true };39  });40}41 42const loads = [43  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 0 },44  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 1 },45  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 2 },46  { url: "/assets/app.8f3a1c.js", content: changedSource, hour: 3 },47  { url: "/assets/tiny.js", content: tinySource, hour: 4 },48  { url: "/assets/app.91bd22.js", content: largeSource, hour: 5 },49  { url: "/assets/app.91bd22.js", content: largeSource, hour: 80 },50];51 52const decisions = decideEngineCacheLoads(loads);53console.log(decisions.map((item) => item.outcome).join(" -> "));54console.log(decisions.map((item) => item.usesCachedBytecode ? "use cache" : "compile").join(" -> "));

1const rules = { minimumSourceBytes: 1024, recentVisitHours: 72 };2const largeSource = "console.log('dashboard shell');\n" +3  "export const route = 'dashboard';\n".repeat(44);4const changedSource = largeSource + "export const build = 'v2';\n";5const tinySource = "console.log('tiny');";6 7function decideEngineCacheLoads(loads) {8  const entries = new Map();9 10  return loads.map((load) => {11    const sizeBytes = load.content.length;12    const previous = entries.get(load.url);13    const changed = previous ? previous.content !== load.content : false;14    const stale = previous ? load.hour - previous.lastSeenHour > rules.recentVisitHours : false;15 16    if (sizeBytes < rules.minimumSourceBytes) {17      return { outcome: "too-small", usesCachedBytecode: false };18    }19 20    if (!previous || changed || stale) {21      entries.set(load.url, {22        content: load.content,23        hits: 1,24        lastSeenHour: load.hour,25        hasDiskCodeCache: false,26      });27      return { outcome: "cold", usesCachedBytecode: false };28    }29 30    previous.hits += 1;31    previous.lastSeenHour = load.hour;32 33    if (!previous.hasDiskCodeCache) {34      previous.hasDiskCodeCache = true;35      return { outcome: "warm", usesCachedBytecode: false };36    }37 38    return { outcome: "hot", usesCachedBytecode: true };39  });40}41 42const loads = [43  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 0 },44  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 1 },45  { url: "/assets/app.8f3a1c.js", content: largeSource, hour: 2 },46  { url: "/assets/app.8f3a1c.js", content: changedSource, hour: 3 },47  { url: "/assets/tiny.js", content: tinySource, hour: 4 },48  { url: "/assets/app.91bd22.js", content: largeSource, hour: 5 },49  { url: "/assets/app.91bd22.js", content: largeSource, hour: 80 },50];51 52const decisions = decideEngineCacheLoads(loads);53console.log(decisions.map((item) => item.outcome).join(" -> "));54console.log(decisions.map((item) => item.usesCachedBytecode ? "use cache" : "compile").join(" -> "));

Notice the important distinction: a warm run is better than a cold network miss, but it is not the same as a disk code-cache hit. In the V8 developer post, the warm run writes serialized metadata that makes the next matching load hot.

Not all startup wins come from reusing old work. V8's Background compilation post says Chrome could parse JavaScript on a background thread via StreamedSource since version 41, starting as soon as the first network chunk arrived. Starting with Chrome 66, V8 moved much of bytecode compilation off the main thread too, reducing main-thread compilation time by about 5–20% on typical websites in their measurements.

There are limits. That post says only top-level script code and immediately invoked function expressions were compiled on a background thread at the time; inner functions still compiled lazily when first executed. Chrome 78 later enabled script streaming during preload, so <link rel="preload" as="script"> could begin compilation before the parser reached the later <script> tag.

1<link rel="preload" as="script" href="/assets/app.js">2<script src="/assets/app.js" defer></script>3 4<script type="module">5  const module = await WebAssembly.compileStreaming(fetch("/app.wasm"));6  console.log(module instanceof WebAssembly.Module);7</script>

WebAssembly exposes the overlap directly with WebAssembly.compileStreaming(fetch(...)). V8's Chrome 65 post says WebAssembly compilation can begin as module bytes arrive and compile functions on background threads. JavaScript does not expose the same compile-streaming API, but the browser can still stream parse and compile eligible scripts internally.

The most useful advice from V8's developer post is deliberately boring: do not change code or URLs unnecessarily. Stable external scripts let HTTP cache, service worker cache, and code cache line up. Random inline source, timestamps in URLs, and per-request generated code make each load look new.

1const scripts = [2  { url: "/assets/app.8f3a1c.js", sourceBytes: 1488, note: "stable hashed file" },3  { url: "/assets/app.js?build=2026-09-26T15:23", sourceBytes: 1488, note: "timestamped URL" },4  { url: "inline", sourceBytes: 640, note: "tiny inline bootstrap" },5];6 7for (const script of scripts) {8  const stableUrl = script.url.includes("8f3a1c");9  const largeEnough = script.sourceBytes >= 1024;10  console.log(script.note + ": " + (stableUrl && largeEnough ? "cache-friendly" : "review"));11}

Production checklist

Startup performance work is most valuable when you pair engine knowledge with product traces. Use it to ask better questions, not to cargo-cult every internal heuristic.

1. Measure first-load and repeat-load traces separately. A code-cache hit cannot fix first visit cost.
2. Keep route entry URLs stable with content hashes; avoid timestamps and random query strings.
3. Keep source bytes stable between deploys unless behavior really changed.
4. Prefer external scripts for non-trivial code; keep inline scripts small and deterministic.
5. Do not generate hot code with eval or new Function unless you have a measured reason.
6. Use service worker precaching only with a versioned cleanup plan.
7. For Node CLIs or servers, test whether startup snapshots or module compile cache help your real launch path.

Common misconceptions

• “HTTP cache and code cache are the same.” HTTP cache stores response bytes. V8 code cache stores compilation metadata for matching source.
• “A startup snapshot runs my app ahead of time.” It starts from prepared heap state; app code still executes after deserialization.
• “Warm means bytecode was reused.” In Chrome's public V8 model, warm is the second load that compiles again and writes disk code-cache metadata.
• “Tiny files always cache better.” Too many tiny scripts can miss code-cache size heuristics and add request and scheduling overhead.
• “Service workers automatically make scripts fast forever.” They can help, but stale caches, quota eviction, encoding/module mismatches, and lifecycle bugs still matter.
• “Streaming compilation is JIT optimization.” It overlaps parse/bytecode compilation with download; optimized JIT tiers still need runtime feedback.

Takeaways and next

• Startup snapshots avoid rebuilding the initialized JavaScript heap for every context or process.
• Lazy deserialization keeps built-in code as placeholders until the isolate actually touches it.
• Code caching reuses parse/compile results for identical source; it is separate from HTTP caching.
• Chrome's public V8 guidance describes cold, warm, and hot runs, a 1 KiB source threshold, and service worker precache advantages.
• Node 22.23.1 has user-land startup snapshots, v8.startupSnapshot, vm.Script cached data, and module compile cache APIs.
• Cache-friendly code keeps URLs and bytes stable, avoids dynamic hot code, and measures first load separately from repeat load.

Next, tiered compilation explains what happens after startup: engines watch running code, collect feedback, and recompile hot paths through interpreter, baseline, mid-tier, and optimizing tiers.