fix(node-renderer): expose performance in VM context when supportModules (#3158)

## Summary

- Adds `performance` to the default globals injected into the node
renderer's VM context when `supportModules: true`.
- React 19's development build of `React.lazy` calls `performance.now()`
inside `lazyInitializer`, which threw `ReferenceError: performance is
not defined` without this — making `React.lazy` unusable in dev unless
users manually passed `performance` via `additionalContext`.
- Updates the `Config` JSDoc, the `js-configuration.md` docs, and the
`CHANGELOG`, and adds a regression test.

Fixes #3154.

## Notes

The reporter also raised a broader question about the recommended
pattern for `React.lazy` with streaming SSR and `LimitChunkCountPlugin({
maxChunks: 1 })` (intermittent Suspense resolution causing hydration
mismatches / React error #419). That's a separate, larger discussion and
is not addressed here — this PR only fixes the concrete `performance`
VM-context bug the reporter identified and worked around.

## Test plan

- [x] `pnpm --filter react-on-rails-pro-node-renderer exec jest vm.test`
— all 27 tests pass, including the new assertions that `performance` and
`performance.now` are defined in the VM when `supportModules` is
enabled.
- [x] `pnpm exec prettier --check` on the modified files — passes.
- [x] `pnpm -w run eslint` on the modified source files — passes.

Generated with Claude Code (https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: adds one additional global (`performance`) to the VM context
behind the existing `supportModules` flag, plus doc/test updates; main
behavioral change is potential nondeterministic SSR output if app code
embeds `performance.now()` values.
> 
> **Overview**
> Fixes React 19 dev SSR crashes by adding the host `performance` object
to the node renderer VM globals when `supportModules: true`, alongside
existing injected Node globals.
> 
> Updates docs and JSDoc to reflect the new default global set and to
clarify that `stubTimers` does not stub `performance` (with guidance for
overriding via `additionalContext`), and extends VM tests to assert
`performance`/`performance.now` presence when enabled (and absence when
disabled).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
54b4aaf. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Restored React 19 dev compatibility by ensuring the renderer VM
includes the performance global when module support is enabled,
preventing ReferenceError in lazy-loaded code.

* **Documentation**
* Clarified that performance is included in the VM globals when module
support is enabled and noted behavior relative to timer stubbing and SSR
determinism.

* **Tests**
* Updated tests to assert performance and performance.now availability
in the VM sandbox.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justin808

CHANGELOG.md

@@ -30,6 +30,7 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 #### Fixed
 
+- **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).
 - **Doctor no longer fails custom projects for a missing generated `bin/dev`**: `react_on_rails:doctor` now downgrades a missing official React on Rails `bin/dev` launcher from an error to a warning and adds explicit guidance when a custom `./dev` script is detected, so custom projects can pass diagnostics when their development setup is intentional. Fixes [Issue 3103](https://github.com/shakacode/react_on_rails/issues/3103). [PR 3117](https://github.com/shakacode/react_on_rails/pull/3117) by [justin808](https://github.com/justin808).

docs/oss/building-features/node-renderer/js-configuration.md

@@ -34,7 +34,8 @@ available default ENV values if you wire them into your own launch script.
 1. **gracefulWorkerRestartTimeout**: (default: `env.GRACEFUL_WORKER_RESTART_TIMEOUT`) - Time in seconds that the master waits for a worker to gracefully restart (after serving all active requests) before killing it. Use this when you want to avoid situations where a worker gets stuck in an infinite loop and never restarts. This config is only usable if worker restart is enabled. The timeout starts when the worker should restart; if it elapses without a restart, the worker is killed.
 1. **maxDebugSnippetLength** (default: 1000) - If the rendering request is longer than this, it will be truncated in exception and logging messages.
 1. **supportModules** - (default: `env.RENDERER_SUPPORT_MODULES || null`) - If set to true, `supportModules` enables the server-bundle code to call a default set of NodeJS global objects and functions that get added to the VM context:
-   `{ Buffer, TextDecoder, TextEncoder, URLSearchParams, ReadableStream, process, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, queueMicrotask }`.
+   `{ Buffer, TextDecoder, TextEncoder, URLSearchParams, ReadableStream, process, performance, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, queueMicrotask }`.
+   `performance` is included so React 19's development build can call `performance.now()` from `React.lazy` without throwing `ReferenceError: performance is not defined`.
    This option is required to equal `true` if you want to use loadable components.
    Setting this value to false causes the NodeRenderer to behave like ExecJS.
    See also `stubTimers`.
@@ -45,6 +46,7 @@ available default ENV values if you wire them into your own launch script.
    This is useful when using dependencies like [react-virtuoso](https://github.com/petyosi/react-virtuoso) that use these functions during hydration.
    In RORP, hydration typically is synchronous and single-task (unless you use streaming) and thus callbacks passed to task-scheduling functions should never run during server-side rendering.
    Because these functions are valid client-side, they are ignored on server-side rendering without errors or warnings.
+   Note that `performance` (exposed when `supportModules: true`) is the host's real `performance` object and is **not** stubbed by `stubTimers`; if rendered output embeds `performance.now()` values (e.g., dev-only timing annotations) they will vary between renders. Override via `additionalContext` (e.g., `{ performance: { now: () => 0 } }`) if strict SSR determinism is required.
    See also `supportModules`.
 
 Deprecated options:

docs/oss/migrating/rsc-troubleshooting.md

@@ -818,7 +818,7 @@ for the current recommendation. See also
 // renderer/node-renderer.js (or wherever you configure the renderer)
 module.exports = {
   supportModules: true, // Injects: Buffer, TextDecoder, TextEncoder,
-  // URLSearchParams, ReadableStream, process,
+  // URLSearchParams, ReadableStream, process, performance,
   // setTimeout, setInterval, setImmediate,
   // clearTimeout, clearInterval, clearImmediate,
   // queueMicrotask
@@ -831,13 +831,16 @@ Or set the environment variable:
 RENDERER_SUPPORT_MODULES=true
 ```
 
-For globals not covered by `supportModules` (e.g., `performance`), use `additionalContext`:
+For globals not covered by `supportModules`, use `additionalContext`:
 
 ```js
 module.exports = {
   supportModules: true,
   additionalContext: {
-    performance: require('perf_hooks').performance,
+    // Add any globals that aren't in the default supportModules set.
+    // Example: override `performance` with a deterministic stub if rendered
+    // output embeds timing values and you need byte-stable SSR.
+    performance: { now: () => 0 },
   },
 };
 ```

packages/react-on-rails-pro-node-renderer/src/shared/configBuilder.ts

@@ -44,7 +44,7 @@ export interface Config {
   bundlePath?: string;
   // If set to true, `supportModules` enables the server-bundle code to call a default set of NodeJS
   // global objects and functions that get added to the VM context:
-  // `{ Buffer, TextDecoder, TextEncoder, URLSearchParams, ReadableStream, process, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, queueMicrotask }`.
+  // `{ Buffer, TextDecoder, TextEncoder, URLSearchParams, ReadableStream, process, performance, setTimeout, setInterval, setImmediate, clearTimeout, clearInterval, clearImmediate, queueMicrotask }`.
   // This option is required to equal `true` if you want to use loadable components.
   // Setting this value to false causes the NodeRenderer to behave like ExecJS.
   supportModules: boolean;

packages/react-on-rails-pro-node-renderer/src/worker/vm.ts

@@ -215,15 +215,17 @@ export async function buildVM(filePath: string) {
 
       if (supportModules) {
         // IMPORTANT: When adding anything to this object, update:
-        // 1. docs/node-renderer/js-configuration.md
-        // 2. packages/node-renderer/src/shared/configBuilder.ts
+        // 1. docs/oss/building-features/node-renderer/js-configuration.md
+        // 2. packages/react-on-rails-pro-node-renderer/src/shared/configBuilder.ts (JSDoc on `supportModules`)
+        // 3. docs/oss/migrating/rsc-troubleshooting.md ("Node Renderer VM Context -- Missing Globals")
         extendContext(contextObject, {
           Buffer,
           TextDecoder,
           TextEncoder,
           URLSearchParams,
           ReadableStream,
           process,
+          performance,
           setTimeout,
           setInterval,
           setImmediate,

packages/react-on-rails-pro-node-renderer/tests/vm.test.ts

@@ -26,7 +26,7 @@ describe('buildVM and runInVM', () => {
     await resetForTest(testName);
   });
 
-  describe('Buffer and process in context', () => {
+  describe('default VM globals (Buffer, process, performance)', () => {
     test('not available if supportModules disabled', async () => {
       const config = getConfig();
       config.supportModules = false;
@@ -35,10 +35,13 @@ describe('buildVM and runInVM', () => {
       await buildVM(uploadedBundlePathForTest());
 
       let result = await runInVM('typeof Buffer === "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
 
       result = await runInVM('typeof process === "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
+
+      result = await runInVM('typeof performance === "undefined"', uploadedBundlePathForTest());
+      expect(result).toBe('true');
     });
 
     test('available if supportModules enabled', async () => {
@@ -49,10 +52,18 @@ describe('buildVM and runInVM', () => {
       await buildVM(uploadedBundlePathForTest());
 
       let result = await runInVM('typeof Buffer !== "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
 
       result = await runInVM('typeof process !== "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
+
+      // React 19's development build of `React.lazy` calls `performance.now()`,
+      // so `performance` must be available when `supportModules` is enabled.
+      result = await runInVM('typeof performance !== "undefined"', uploadedBundlePathForTest());
+      expect(result).toBe('true');
+
+      result = await runInVM('typeof performance.now === "function"', uploadedBundlePathForTest());
+      expect(result).toBe('true');
     });
   });
 
@@ -62,7 +73,7 @@ describe('buildVM and runInVM', () => {
       await buildVM(uploadedBundlePathForTest());
 
       const result = await runInVM('typeof testString === "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
     });
 
     test('available if additionalContext set', async () => {
@@ -73,7 +84,7 @@ describe('buildVM and runInVM', () => {
       await buildVM(uploadedBundlePathForTest());
 
       const result = await runInVM('typeof testString !== "undefined"', uploadedBundlePathForTest());
-      expect(result).toBeTruthy();
+      expect(result).toBe('true');
     });
   });