Use Case

As a Node.js application developer using the MongoDB driver in an ESM server build,
I want the driver to avoid raw CommonJS require() calls in runtime code paths,
So that the driver can run correctly when bundled into an ESM Node application.

User Experience

• Expected outcome: mongodb should run successfully in a bundled ESM Node server build without throwing "ReferenceError: require is not defined".
• Actual outcome: mongodb@7.2.0 fails at startup when bundled into ESM output because src/runtime_adapters.ts contains: os: options.runtimeAdapters?.os ?? require('os')
• Runtime error:

    ReferenceError: require is not defined
        at resolveRuntimeAdapters (.../dist/index.js:307596:39)
        at parseOptions (.../dist/index.js:311307:76)
        at new MongoClient (.../dist/index.js:314974:59)
    

• In my case this is triggered through:

    @shopify/shopify-app-session-storage-mongodb@6.0.0
    └── mongodb@7.2.0
    

• Known impacted customers: at least one.
• Severity: high for affected bundled ESM server builds because the application is blocked from starting.

Dependencies

• This affects setups where mongodb is bundled into ESM Node output.
• My setup:

    mongodb@7.2.0
    Node >= 22
    Vite backend build
    ESM output
    package.json has "type": "module"
    mongodb is bundled into dist/index.js
    

• Downstream package involved in my case: @shopify/shopify-app-session-storage-mongodb@6.0.0.

Risks/Unknowns

• The problematic code appears to be in src/runtime_adapters.ts:

    os: options.runtimeAdapters?.os ?? require('os')
    

• Potential risks include preserving CommonJS behavior while making this ESM/bundler-safe.
• The fix should preserve the runtime adapter behavior introduced in v7.2.0.
• Bundlers may handle Node built-ins differently, so this may need coverage beyond direct Node execution.
• There may be an opportunity to improve testing for ESM server bundling compatibility.
• There may be an opportunity to document whether bundling mongodb into ESM output is supported, unsupported, or requires externalization.

Acceptance Criteria

Implementation Requirements

• Constructing a MongoClient must not throw `require is not defined` in a bundled ESM build.
• `os` must still be loaded lazily, not at module-parse time
• CommonJS usage should continue to work.
• Existing runtimeAdapters.os behavior should continue to work when explicitly provided.

Testing Requirements

• Update tests for resolveRuntimeAdapters (os provided and omitted)
• Add a targeted bundling/runtime test for the `os` runtime adapter: bundle it to ESM and in Node with no global `require`

Documentation Requirements

• None (This is still an experimental feature and we do not currently have ESM-specific documentation)

Follow Up Requirements

• Add way to run all unit and integ tests against the Node Driver in an ESM bundle: https://jira.mongodb.org/browse/NODE-7633