Is esbuild translating `const somelib = require("somelib"); into the appropriate ESM notation?

[eauchat]

I had an issue with using underscore with esbuild, and reported it to underscore's issue tracker. But it seems the issue may be due to esbuild so I thought to bring back the issue here.
I'm not versed enough neither into underscore nor into esbuild to evaluate the situation, but from the nice and detailed explanations a maintainer of underscore gave me, I understand the following:

The following:

const _ = require("underscore");

may be translated to:

import * as _ from 'underscore';

by esbuild, while the expectation from underscore's maintainers is that it would be translated to:

import _ from 'underscore';

This causes some issues as outlined in this issue.
The detailed answer from @jgonggrijp also gives much more explanations and background.

I'm just making myself the messenger here, in case that would be a useful feedback for esbuild. But I'm aware that may be a voluntary choice for esbuild to behave this way. So feel free to close this issue if you don't find it relevant. The issue is not big and there are workarounds, so I wrote this issue just in case that's of any use for improving esbuild.
In any case thanks for the great tool :)

[chirsz-ever]

I used the following steps and code to reproduce your problem：

• In a new folder, run npm install underscore@1.13.8
• Create test.js:

  var _ = require("underscore");
  console.log(_ === _.partial.placeholder);

• Run node test.js, the output is "true"
• Run esbuild --platform=node --format=esm --bundle test.js --outfile=test-bundle.js, generating test-bundle.js
• Run node test-bundle.js, the output is "false"

The reason for the inconsistent results between the two runs is that Node.js resolves require("underscore") to exports["."].require.node in underscore's package.json, which is ./underscore-node.cjs; while esbuild resolves it to exports["."].require.module, which is ./modules/index-all.js. This results that in esbuild require("underscore") produces a wrapped Module object instead of an Underscore instance.

The module field is imported in jashkenas/underscore@89b32a6. This is to solve the problem that import syntax and require imports cause the bundler to import two copies of Underscore code.

I think this isn't a problem with Underscore or esbuild, but rather a historical legacy issue from the long-term development of the JavaScript language and runtime.

I have two solutions:

1. Since you're already using a bundler, the best practice is to always use ES Module syntax, for example:

import _ from "underscore";
console.log(_ === _.partial.placeholder);

This will avoid the problem.
2. Use the conditions option of esbuild. For example:

// test.js
var _ = require("underscore");
console.log(_ === _.partial.placeholder);

Run esbuild --platform=node --format=esm --bundle test.js --conditions=node --outfile=test-bundle.js. This time, esbuild will not read the "module" field, but will instead resolve require("underscore") to underscore-node.cjs file, just like Node.js. Running node test-bundle.js will output true.

Related:

• https://joyeecheung.github.io/blog/2025/12/30/require-esm-in-node-js-implementers-tales
• https://webpack.js.org/guides/package-exports/#target-environment-independent-packages
• https://nodejs.org/docs/latest-v18.x/api/packages.html#dual-package-hazard

[jgonggrijp]

The reason for the inconsistent results between the two runs is that Node.js resolves require("underscore") to exports["."].require.node in underscore's package.json, which is ./underscore-node.cjs; while esbuild resolves it to exports["."].require.module, which is ./modules/index-all.js. This results that in esbuild require("underscore") produces a wrapped Module object instead of an Underscore instance.

The module field is imported in jashkenas/underscore@89b32a6. This is to solve the problem that import syntax and require imports cause the bundler to import two copies of Underscore code.

Sure, but,

I think this isn't a problem with Underscore or esbuild, but rather a historical legacy issue from the long-term development of the JavaScript language and runtime.

I have to disagree here. While esbuild can and should create a module wrapper object from underscore/modules/index-all.js, it still has a choice between emulating var _ = require('underscore') as import * as _ from 'underscore' (all of the module wrapper) or import _ from 'underscore' (just the default entry from the module wrapper). This is not a historical accident but a deliberate design choice in esbuild. esbuild is presently choosing the first option and I think this is the less-compatible, if not incorrect option.

• https://nodejs.org/docs/latest-v18.x/api/packages.html#dual-package-hazard

FWIW I have consulted the above source and followed all advices. The present issue is NOT a necessary consequence of Underscore's package structure; rollup for example does not have this issue.

[chirsz-ever]

rollup for example does not have this issue.

I encountered the same problem when testing rollup. Could you please help me test this gist?

[jgonggrijp]

Thanks. I can confirm that your gist with rollup has this issue, too. This appears to be a breaking change in version 15 of @rollup/plugin-commonjs; with earlier versions, the bundle outputs true. I will be reporting this to them.

I stand by my earlier point that this is not just historical accident but there is a deliberate design choice in play. The old x = require('package') is compatible with ESM default imports but not with ESM namespace imports, because libraries from the CommonJS era like jQuery and Underscore rely on the possibility to refer to the whole export from within the package and also on the possibility to make the "whole export" any value of choice including a function. module.exports is also conceptually much closer to the default export than to ESM's namespace wrapper; the latter would be more similar to module itself, which however was not accessible to outside users in CommonJS.

[chirsz-ever]

This change was introduced by rollup/plugins#507. It also adds the requireReturnsDefault option to revert to previous behavior.

The semantics of require(esm) actually supported by various bundlers and Node.js in recent years are basically consistent, and I don't think there will be any major changes in the future; a unified semantics should be used to maintain standardization.

I think this problem can be solved by the export { x as "module.exports" } feature added by Node.js:

To customize what should be returned by require(esm) directly, the ES Module can export the desired value using the string name "module.exports".

You just need to add

export { default as "module.exports" } from './index-default.js';

to modules/index-all.js, and then wait for all bundlers to support this feature. For example, rolldown already supports it (playground).

[jgonggrijp]

OK. I stand corrected, apparently everyone settled on the other option. Thanks for the hint. Do you also know where I can find the discussion in which this was decided? I can't make sense of it, but if this is the route that was chosen as a consensus, I will comply.

[chirsz-ever]

Do you also know where I can find the discussion in which this was decided?

If you're referring to the "module.exports" string name export, a vote selected it.

More related discussions:

• https://joyeecheung.github.io/blog/2025/12/30/require-esm-in-node-js-implementers-tales/#CommonJS-special-module-exports-string-name-export
• module: support 'module.exports' interop export name in require(esm) nodejs/node#54563
• Naming bikeshed - require(esm) interop flag nodejs/loaders#221

[jgonggrijp]

Thanks, will read.

[eauchat]

Thanks to both for the constructive discussion, interesting read :)
And thanks a lot @chirsz-ever for all the explanations and resources. From reading all this I have the feeling maybe this issue can be closed. I'll close it but if any of you feel it shouldn't be I can reopen it.