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

• mongodb should not fail with "ReferenceError: require is not defined" when used in a bundled ESM Node server build.
• CommonJS usage should continue to work.
• Existing runtimeAdapters.os behavior should continue to work when explicitly provided.

Testing Requirements

• Add or update tests for resolveRuntimeAdapters.
• Add a bundling/runtime test that verifies mongodb can be bundled into ESM output and run in Node without global require.
• Test both cases where runtimeAdapters.os is provided and where runtimeAdapters.os is omitted.

Documentation Requirements

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

Follow Up Requirements

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