`import` fails to resolve when using `esbuild` build tool

[wang1212]

Is your feature request related to a problem? Please describe.

When using the esbuild build tool, the import statement reports an error that cannot be resolved.

E.g:

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';

This is because of the following configuration:

"exports": {
  "./examples/jsm/*": "./examples/jsm/*"
}

Although tools like rollup, webpack, etc. may be normal, obviously esbuild respects node specification standards more.

According to the node specification, in order for the esbuild tool to work properly, the file extension needs to be added:

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

Obviously when this happens, many people need to spend as much time as I do to analyze the cause of the problem.

In fact, the following configuration can also solve the problem:

"exports": {
  "./examples/jsm/*": "./examples/jsm/*.js" 
}

In order to improve development efficiency (compilation speed), esbuild should have been widely used, can this problem be solved?

see also evanw/esbuild#2518

Describe the solution you'd like

1. For files of the same type (such as .js), change the exports configuration in package.json, for example

"exports": {
  "./examples/jsm/*": "./examples/jsm/*.js"
}

2. For different categories of files contained in a folder, multiple configurations can be written, or it is clearly mentioned in the documentation that developers should write extensions when importing?

"exports": {
  "./examples/jsm/*.js": "./examples/jsm/*.js",
  "./examples/jsm/*.png": "./examples/jsm/*.png"
}

Describe alternatives you've considered

Additional context

[gkjohnson]

If you'd like esbuild to be more flexible in its ability to resolve package paths I recommend making an issue or PR to the esbuild project rather than one here. But either way it is not common for packages to export files in the style you have recommended. And as you've mentioned this kind of export can lead to file ambiguity. It's best to explicitly import the files you want to your project. You can see that even react-dom does not export files in a way that affords dropping the file extension.

[donmccurdy]

I thought omitting the .js extension on imports was mostly a TypeScript-ism, is it used outside TS?

I don't think we should be doing that anywhere within this project, including examples...

[gkjohnson]

I thought omitting the .js extension on imports was mostly a TypeScript-ism, is it used outside TS?

Yes... Again see here in react-dom.

If people want to use a unique, non-standard style of file imports like this they'll need to configure their build system to support it. It can't be each packages responsibility to accommodate it.

[CodyJasonBennett]

Explicit file extensions are required since threejs is an ES module. It's not correct to blame other tools for following node resolution, they're working as intended.

[LeviPesin]

I don't like extension-less imports because they are confusing (no one reading the code would be able to understand whether the code imports JS file, TS file, or even a CSS file) and they wouldn't work if there are multiple files with the same names but different extensions.

[marcofugaro]

Esbuild is following the ES Modules specification (not node), which requires the .js extension to be specified when importing.

Other bundlers (like webpack) allow you to omit the .js extension if you want. But that decision relies on the bundler.

[wang1212]

Everyone seems to have their own reasons, so is the package.json file a configuration file that belongs to a node module? Was this fact deliberately ignored? For the front-end development ecosystem, node is an engineering infrastructure. Does it make sense to talk about this issue aside from the fact that the package.json file is used as the configuration file of the node module?

Does a package.json file make sense when using a CDN to reference dependencies?

For whether node allows to ignore file extensions, please refer to the official documentation here: --experimental-specifier-resolution=node

I noticed that some people gave examples of react-dom configuration, but in actual development, how many developers will refer to react-dom/src/* files? And a lot of sample code of threejs is very commonly used.

Changing the package.json configuration item is just a suggestion, adding FAQ is also an option, the purpose is to improve the development experience of developers, that's all.

[donmccurdy]

@wang1212 the files you are importing have .js extensions on disk. There is nothing in the ES Module specification that says you can omit the .js extension from an import. Some build tools just happen to allow it.

If you prefer to use that style of imports, and are not using a build tool that enables them by default, I think we have to ask you to configure your build tool accordingly. I do not think it's a good idea for packages like three.js to alias those rewrites themselves; we will cause more problems than we solve unfortunately.

[CodyJasonBennett]

Yes... Again see here in react-dom.

If people want to use a unique, non-standard style of file imports like this they'll need to configure their build system to support it. It can't be each packages responsibility to accommodate it.

This isn't correct, and you shouldn't be consulting react internals as to how to configure packages; react is a very complex and involved codebase. react-dom/src/* is not a public entrypoint, they locally expose internals for sharing and inline dependencies at build-time as CJS. See https://unpkg.com/react-dom@18.2.0/package.json. Notice how they alias react-dom/client to react-dom/client.js and react-dom/server to react-dom/server.js, respectively. Those are flat bundles that are intended to be imported without an extension. Three doesn't make use of flat bundles in subpaths (e.g. #23368) but exports three/examples/* as ESM source code and assets. This is very unique to three, I don't recall many packages that ship source code in another folder if not for source maps.

@wang1212 the files you are importing have .js extensions on disk. There is nothing in the ES Module specification that says you can omit the .js extension from an import. Some build tools just happen to allow it.

To clarify, NPM packages follow Node specification and resolution between ESM and CJS, and three ships examples as ESM-only. Some tools may transpile and allow omitting file extensions for interop (CJS doesn't have this restriction). Vite, based on rollup and esbuild, would be the most notable to do this due to its stack and use across frontend, backend, and testing. I'd recommend that for @wang1212 if their project allows it.

If you prefer to use that style of imports, and are not using a build tool that enables them by default, I think we have to ask you to configure your build tool accordingly. I do not think it's a good idea for packages like three.js to alias those rewrites themselves; we will cause more problems than we solve unfortunately.

I see that the proposed alias was actually reverted via 528193f of r137. Why is that? Is it not worthwhile to support both methods of imports for JS via https://nodejs.org/api/packages.html#package-entry-points? This would also work with #24595.

// Hypothetical but pertinent to #23368
"./addons": "./examples/jsm/index.js",

"./examples/fonts/*": "./examples/fonts/*",

"./addons/*": "./examples/jsm/*",
"./addons/*.js": "./examples/jsm/*.js",
"./examples/*": "./examples/jsm/*",
"./examples/*.js": "./examples/jsm/*.js",

Otherwise, has this since been documented, or is there no need to? I'm not sure if it's a breaking change but a source of confusion for sure.

[gkjohnson]

This isn't correct, and you shouldn't be consulting react internals as to how to configure packages; react is a very complex and involved codebase.

My only point in that post was that there are large packages choosing to omit extensions in their imports and that it requires a specialized build system to support.

[CodyJasonBennett]

I don't understand what you're saying. I'm sure there's been internal dialogue and patch releases around this (noting 528193f, specifically), but surely the above configuration wouldn't be such a maintenance concern. It is my understanding that it is purely beneficial for user-land.

[gkjohnson]

It was a response to #24593 (comment) asking whether this only happened in TS.

(noting 528193f, specifically)

The extensions were removed within days of being the exports initially being added (and before a release was made) and likely because the previous implementation with .js precluded the ability to import files with the extension. Three.js has always been designed around writing, distributing, and encouraging code that can be run directly in the browser so I don't expect the project would have deliberately been enabling exports that encouraged extension-less paths that required a build process.

There are lots of ways that people to structure and organize their code. If users have a preferred ergonomic way to import files then more power to them - but I don't think it's three.js' job to directly accommodate all of them. Users can configure their build process to support their ergonomic preferences. Otherwise in userland this is inconsequential. Everything still works all the same.

If someone else on the project is interested in getting this changed added that's fine but I don't expect my opinions are all that divergent from the project opinions on the topic.

[CodyJasonBennett]

How is it not strictly correct for a package published on NPM using an NPM-specific package.json file to prevent the most common and painful interop issue that presents a user-land gotcha through a seemingly trivial and supported configuration?

I don't understand why this is reduced to ergonomics; it otherwise makes authoring on top of three, especially a library, very error-prone and confusing in sometimes unfixable ways, especially if you forgo a build tool that would abstract this away. This is why I bother to comment, and one of the concerns of pmndrs/three-stdlib, aside from tree-shaking, both of which I would really like to be able to contribute here and make redundant following #24595.

I want three examples or addons to be easy and safe to use for end-users, particularly for modern stacks. What can I or we do to get there because I don't see an alternative?