From ffc400031287855f91e2b7408ac0662304d52fd1 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Wed, 6 May 2026 00:23:17 +0200
Subject: [PATCH] lib: expose `v8.startupSnapshot` functions on `globalThis`

Expose methods from `require('v8').startupSnapshot` which are
relevant for isomorphic libraries through a `Symbol`-indexed
property on the global object.

This provides a mechanism for using these functions from libraries
that do not integrate with Node.js's module system, while still
enabling integration with the startup snapshot mechanism.
It also provides a path for exposing this feature from other
runtimes that support a startup-snapshot-style feature.

We do not typically expose runtime-specific/non-standard
capabilities on the global object, so using a `Symbol` property
seems like the best way to avoid any potential naming conflicts
and its consequences.

Signed-off-by: Anna Henningsen <anna@addaleax.net>
---
 doc/api/globals.md                            | 19 +++++++++++++++++++
 doc/api/v8.md                                 | 12 ++++++++++++
 lib/internal/process/pre_execution.js         |  8 ++++++++
 lib/internal/v8/startup_snapshot.js           | 10 ++++++++++
 src/node_util.cc                              |  4 ++--
 test/parallel/test-v8-startup-snapshot-api.js |  8 ++++++++
 6 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/doc/api/globals.md b/doc/api/globals.md
index a70442f1bb91ec..66e61eb40a8c79 100644
--- a/doc/api/globals.md
+++ b/doc/api/globals.md
@@ -1352,6 +1352,24 @@ changes:
 
 A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 
+## `[Symbol.for('startupSnapshot')]`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An object exposing the `addDeserializeCallback`, `addSerializeCallback`, and `isBuildingSnapshot`
+methods from [`v8.startupSnapshot`][] for usage in libraries that target both Node.js and other
+runtimes and cannot directly rely on the `v8` module.
+
+```js
+const {
+  addDeserializeCallback,
+  addSerializeCallback,
+  isBuildingSnapshot,
+} = globalThis[Symbol.for('startupSnapshot')];
+```
+
 [CommonJS module]: modules.md
 [CommonJS modules]: modules.md
 [ECMAScript module]: esm.md
@@ -1422,6 +1440,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [`setInterval`]: timers.md#setintervalcallback-delay-args
 [`setTimeout`]: timers.md#settimeoutcallback-delay-args
 [`structuredClone`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone
+[`v8.startupSnapshot`]: v8.md#startup-snapshot-api
 [`window.navigator`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/navigator
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [browser `LockManager`]: https://developer.mozilla.org/en-US/docs/Web/API/LockManager
diff --git a/doc/api/v8.md b/doc/api/v8.md
index da225a333ddcac..a7c7f89aab39d3 100644
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@@ -1400,6 +1400,10 @@ into a form more suitable for serialization.
 
 Callbacks are run in the order in which they are added.
 
+This function is also available as
+`globalThis[Symbol.for('startupSnapshot')].addSerializeCallback` for use
+in libraries that cannot import the `v8` module.
+
 ### `v8.startupSnapshot.addDeserializeCallback(callback[, data])`
 
 <!-- YAML
@@ -1421,6 +1425,10 @@ when the application is restarted from the snapshot.
 
 Callbacks are run in the order in which they are added.
 
+This function is also available as
+`globalThis[Symbol.for('startupSnapshot')].addDeserializeCallback` for use
+in libraries that cannot import the `v8` module.
+
 ### `v8.startupSnapshot.setDeserializeMainFunction(callback[, data])`
 
 <!-- YAML
@@ -1453,6 +1461,10 @@ added:
 
 Returns true if the Node.js instance is run to build a snapshot.
 
+This function is also available as
+`globalThis[Symbol.for('startupSnapshot')].isBuildingSnapshot` for use
+in libraries that cannot import the `v8` module.
+
 ## Class: `v8.GCProfiler`
 
 <!-- YAML
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 16a80c2d4f410f..c2aeefbbadad72 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -13,6 +13,7 @@ const {
   ObjectDefineProperty,
   ObjectFreeze,
   String,
+  SymbolFor,
   globalThis,
 } = primordials;
 
@@ -123,6 +124,7 @@ function prepareExecution(options) {
   setupEventsource();
   setupCodeCoverage();
   setupDebugEnv();
+  setupGlobalSnapshotHooks();
   // Process initial diagnostic reporting configuration, if present.
   initializeReport();
 
@@ -378,6 +380,12 @@ function setupNavigator() {
   defineReplaceableLazyAttribute(globalThis, 'internal/navigator', ['navigator'], false);
 }
 
+function setupGlobalSnapshotHooks() {
+  exposeLazyInterfaces(globalThis, 'internal/v8/startup_snapshot', [
+    SymbolFor('startupSnapshot'),
+  ]);
+}
+
 function setupFFI() {
   if (!getOptionValue('--experimental-ffi')) {
     return;
diff --git a/lib/internal/v8/startup_snapshot.js b/lib/internal/v8/startup_snapshot.js
index a7f9ebcf779bd6..dd80995b9512f0 100644
--- a/lib/internal/v8/startup_snapshot.js
+++ b/lib/internal/v8/startup_snapshot.js
@@ -1,5 +1,9 @@
 'use strict';
 
+const {
+  SymbolFor,
+} = primordials;
+
 const {
   validateFunction,
 } = require('internal/validators');
@@ -122,6 +126,12 @@ initializeCallbacks();
 module.exports = {
   runDeserializeCallbacks,
   throwIfBuildingSnapshot,
+  // Exposed to globalThis[Symbol.for('startupSnapshot')]
+  [SymbolFor('startupSnapshot')]: {
+    addDeserializeCallback,
+    addSerializeCallback,
+    isBuildingSnapshot,
+  },
   // Exposed to require('v8').startupSnapshot
   namespace: {
     addDeserializeCallback,
diff --git a/src/node_util.cc b/src/node_util.cc
index 8be8a8b5726a26..a6803f210d6312 100644
--- a/src/node_util.cc
+++ b/src/node_util.cc
@@ -422,10 +422,10 @@ static void DefineLazyProperties(const FunctionCallbackInfo<Value>& args) {
       // V8 will have scheduled an error to be thrown.
       return;
     }
-    CHECK(key->IsString());
+    CHECK(key->IsName());
     if (target
             ->SetLazyDataProperty(context,
-                                  key.As<String>(),
+                                  key.As<Name>(),
                                   DefineLazyPropertiesGetter,
                                   id,
                                   attribute)
diff --git a/test/parallel/test-v8-startup-snapshot-api.js b/test/parallel/test-v8-startup-snapshot-api.js
index c3738911540fc1..3daecc7631a30a 100644
--- a/test/parallel/test-v8-startup-snapshot-api.js
+++ b/test/parallel/test-v8-startup-snapshot-api.js
@@ -24,3 +24,11 @@ assert.throws(() => addDeserializeCallback(() => {}), {
 assert.throws(() => setDeserializeMainFunction(() => {}), {
   code: 'ERR_NOT_BUILDING_SNAPSHOT',
 });
+
+// globalThis[Symbol.for('startupSnapshot')] provides access to a subset
+// of functions.
+assert.deepStrictEqual(globalThis[Symbol.for('startupSnapshot')], {
+  addDeserializeCallback,
+  addSerializeCallback,
+  isBuildingSnapshot,
+});