Fix require() to return mutable exports for Node.js compat

Author: anonrig

src/workerd/api/global-scope.c++

@@ -928,8 +928,11 @@ jsg::JsValue ServiceWorkerGlobalScope::getBuffer(jsg::Lock& js) {
       // that set the bufferValue, we let's check again.
       return p.getHandle(js);
     }
-    auto def = module.get(js, "default"_kj);
-    auto obj = KJ_ASSERT_NONNULL(def.tryCast<jsg::JsObject>());
+    // When requireReturnsDefaultExport flag is enabled, resolveModule returns the
+    // default export directly. Otherwise it returns the module namespace.
+    auto obj = module.has(js, "default"_kj)
+        ? KJ_ASSERT_NONNULL(module.get(js, "default"_kj).tryCast<jsg::JsObject>())
+        : module;
     auto buffer = obj.get(js, "Buffer"_kj);
     JSG_REQUIRE(buffer.isFunction(), TypeError, "Invalid node:buffer implementation");
     bufferValue = jsg::JsRef(js, buffer);
@@ -970,7 +973,9 @@ jsg::JsValue ServiceWorkerGlobalScope::getProcess(jsg::Lock& js) {
       // that set the processValue, we let's check again.
       return p.getHandle(js);
     }
-    auto def = module.get(js, "default"_kj);
+    // When requireReturnsDefaultExport flag is enabled, resolveInternalModule returns the
+    // default export directly. Otherwise it returns the module namespace.
+    auto def = module.has(js, "default"_kj) ? module.get(js, "default"_kj) : jsg::JsValue(module);
     JSG_REQUIRE(def.isObject(), TypeError, "Invalid node:process implementation");
     processValue = jsg::JsRef(js, def);
     return def;

src/workerd/api/node/tests/BUILD.bazel

@@ -228,6 +228,12 @@ wd_test(
     data = ["module-create-require-test.js"],
 )
 
+wd_test(
+    src = "module-require-mutable-exports-test.wd-test",
+    args = ["--experimental"],
+    data = ["module-require-mutable-exports-test.js"],
+)
+
 wd_test(
     src = "process-exit-test.wd-test",
     args = ["--experimental"],

src/workerd/api/node/tests/module-create-require-test.js

@@ -14,14 +14,28 @@ export const doTheTest = {
     const baz = require('baz');
     const qux = require('worker/qux');
 
-    strictEqual(foo.default, 1);
+    // When require_returns_default_export flag is enabled, require() returns the
+    // default export directly. Otherwise it returns the namespace object.
+    if (Cloudflare.compatibilityFlags.require_returns_default_export) {
+      strictEqual(foo, 1);
+    } else {
+      strictEqual(foo.default, 1);
+    }
     strictEqual(bar, 2);
     strictEqual(baz, 3);
     strictEqual(qux, '4');
 
     const assert = await import('node:assert');
     const required = require('node:assert');
-    strictEqual(assert, required);
+
+    // When require_returns_default_export flag is enabled, require() returns the
+    // default export directly (assert.default === required).
+    // When the flag is disabled, require() returns the namespace (assert === required).
+    if (Cloudflare.compatibilityFlags.require_returns_default_export) {
+      strictEqual(assert.default, required);
+    } else {
+      strictEqual(assert, required);
+    }
 
     throws(() => require('invalid'), {
       message: 'Top-level await in module is not permitted at this time.',

src/workerd/api/node/tests/module-require-mutable-exports-test.js

@@ -0,0 +1,122 @@
+// Copyright (c) 2017-2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+import { createRequire } from 'node:module';
+import { strictEqual, ok, doesNotThrow } from 'node:assert';
+
+const require = createRequire('/');
+
+export const testTimersPromisesMutable = {
+  test() {
+    const timersPromises = require('node:timers/promises');
+    const originalSetImmediate = timersPromises.setImmediate;
+    ok(typeof originalSetImmediate === 'function');
+
+    const patchedSetImmediate = async function patchedSetImmediate() {
+      return 'patched';
+    };
+
+    doesNotThrow(() => {
+      timersPromises.setImmediate = patchedSetImmediate;
+    });
+
+    strictEqual(timersPromises.setImmediate, patchedSetImmediate);
+    timersPromises.setImmediate = originalSetImmediate;
+    strictEqual(timersPromises.setImmediate, originalSetImmediate);
+  },
+};
+
+export const testTimersMutable = {
+  test() {
+    const timers = require('node:timers');
+    const originalSetTimeout = timers.setTimeout;
+    ok(typeof originalSetTimeout === 'function');
+
+    const patchedSetTimeout = function patchedSetTimeout() {
+      return 'patched';
+    };
+
+    doesNotThrow(() => {
+      timers.setTimeout = patchedSetTimeout;
+    });
+
+    strictEqual(timers.setTimeout, patchedSetTimeout);
+    timers.setTimeout = originalSetTimeout;
+  },
+};
+
+export const testBufferMutable = {
+  test() {
+    const buffer = require('node:buffer');
+    const originalBuffer = buffer.Buffer;
+    ok(typeof originalBuffer === 'function');
+
+    const patchedBuffer = function PatchedBuffer() {
+      return 'patched';
+    };
+
+    doesNotThrow(() => {
+      buffer.Buffer = patchedBuffer;
+    });
+
+    strictEqual(buffer.Buffer, patchedBuffer);
+    buffer.Buffer = originalBuffer;
+  },
+};
+
+export const testUtilMutable = {
+  test() {
+    const util = require('node:util');
+    const originalPromisify = util.promisify;
+    ok(typeof originalPromisify === 'function');
+
+    const patchedPromisify = function patchedPromisify() {
+      return 'patched';
+    };
+
+    doesNotThrow(() => {
+      util.promisify = patchedPromisify;
+    });
+
+    strictEqual(util.promisify, patchedPromisify);
+    util.promisify = originalPromisify;
+  },
+};
+
+export const testRequireCachesMutableObject = {
+  test() {
+    const timersPromises1 = require('node:timers/promises');
+    const timersPromises2 = require('node:timers/promises');
+
+    strictEqual(timersPromises1, timersPromises2);
+
+    const patchedSetImmediate = async function patched() {
+      return 'patched';
+    };
+    const original = timersPromises1.setImmediate;
+
+    timersPromises1.setImmediate = patchedSetImmediate;
+    strictEqual(timersPromises2.setImmediate, patchedSetImmediate);
+    timersPromises1.setImmediate = original;
+  },
+};
+
+// When require_returns_default_export is enabled, require() should return the
+// default export directly (which is the object with all the functions),
+// not the namespace wrapper with both `default` and named exports.
+export const testRequireReturnsDefaultExport = {
+  test() {
+    const timers = require('node:timers');
+    // With require_returns_default_export enabled, timers should be the
+    // default export object directly, not the namespace wrapper.
+    // The default export IS the object with setTimeout, setInterval, etc.
+    ok(typeof timers.setTimeout === 'function');
+    ok(typeof timers.setInterval === 'function');
+    ok(typeof timers.clearTimeout === 'function');
+    ok(typeof timers.clearInterval === 'function');
+    // The namespace wrapper would have a 'default' property, but when
+    // we return the default export directly, there's no 'default' property
+    // on the returned object (unless the default export itself has one).
+    strictEqual(timers.default, undefined);
+  },
+};

src/workerd/api/node/tests/module-require-mutable-exports-test.wd-test

@@ -0,0 +1,14 @@
+using Workerd = import "/workerd/workerd.capnp";
+
+const unitTests :Workerd.Config = (
+  services = [
+    ( name = "module-require-mutable-exports-test",
+      worker = (
+        modules = [
+          (name = "worker", esModule = embed "module-require-mutable-exports-test.js")
+        ],
+        compatibilityFlags = ["nodejs_compat", "require_returns_default_export"],
+      )
+    ),
+  ],
+);

src/workerd/io/compatibility-date.capnp

@@ -1316,4 +1316,14 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
   # Node.js-compatible versions from node:timers. setTimeout and setInterval return
   # Timeout objects with methods like refresh(), ref(), unref(), and hasRef().
   # This flag requires nodejs_compat or nodejs_compat_v2 to be enabled.
+
+  requireReturnsDefaultExport @154 :Bool
+    $compatEnableFlag("require_returns_default_export")
+    $compatDisableFlag("require_returns_namespace")
+    $compatEnableDate("2026-01-22");
+  # When enabled, require() will return the default export of a module if it exists.
+  # If the default export does not exist, it falls back to returning the mutable
+  # module namespace object. This matches the behavior that Node.js uses for
+  # require(esm) where the default export is returned when available.
+  # This flag is useful for frameworks like Next.js that expect to patch module exports.
 }

src/workerd/io/worker.c++

@@ -1107,6 +1107,9 @@ Worker::Isolate::Isolate(kj::Own<Api> apiParam,
     if (features.getEnableNodeJsProcessV2()) {
       lock->setNodeJsProcessV2Enabled();
     }
+    if (features.getRequireReturnsDefaultExport()) {
+      lock->setRequireReturnsDefaultExportEnabled();
+    }
     if (features.getThrowOnUnrecognizedImportAssertion()) {
       lock->setThrowOnUnrecognizedImportAssertion();
     }

src/workerd/jsg/jsg.c++

@@ -219,6 +219,10 @@ void Lock::setNodeJsProcessV2Enabled() {
   IsolateBase::from(v8Isolate).setNodeJsProcessV2Enabled({}, true);
 }
 
+void Lock::setRequireReturnsDefaultExportEnabled() {
+  IsolateBase::from(v8Isolate).setRequireReturnsDefaultExportEnabled({}, true);
+}
+
 void Lock::setThrowOnUnrecognizedImportAssertion() {
   IsolateBase::from(v8Isolate).setThrowOnUnrecognizedImportAssertion();
 }

src/workerd/jsg/jsg.h

@@ -2647,6 +2647,7 @@ class Lock {
 
   void setNodeJsCompatEnabled();
   void setNodeJsProcessV2Enabled();
+  void setRequireReturnsDefaultExportEnabled();
   void setThrowOnUnrecognizedImportAssertion();
   bool getThrowOnUnrecognizedImportAssertion() const;
   void setToStringTag();

src/workerd/jsg/jsvalue.h

@@ -465,6 +465,11 @@ class JsObject final: public JsBase<v8::Object, JsObject> {
 
   int hashCode() const;
 
+  // Returns true if this object is an ES module namespace object.
+  bool isModuleNamespaceObject() const {
+    return inner->IsModuleNamespaceObject();
+  }
+
   kj::String getConstructorName() KJ_WARN_UNUSED_RESULT;
   JsArray getPropertyNames(Lock& js,
       KeyCollectionFilter keyFilter,