correct exports of extensionless imports

[jgaardsted]

Description

The exports field in three.js package.json is incorrectly specified.
It is specified like this, and missing the .js extensions on the right hand side:
(I should probably file this as reproducible bug instead of as a feature request)

{
  "exports": {
    ".": {
      "import": "./build/three.module.js",
      "require": "./build/three.cjs"
    },
    "./examples/fonts/*": "./examples/fonts/*",
    "./examples/jsm/*": "./examples/jsm/*",
    "./addons/*": "./examples/jsm/*",
    "./src/*": "./src/*",
    "./nodes": "./examples/jsm/nodes/Nodes.js"
  },
}

Solution

The solution is to correctly specify them like this:

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

Alternatives

Currently, this must be worked around with a bundler that alleviates this with some sort of aliasing mechanism,
like vite. But it is unfortunate that this issue dictates which bundlers can/can't be used.

Additional context

The issue is discussed on stackoverflow in detail here:
https://stackoverflow.com/questions/77237284/getting-rollup-to-resolve-extensionless-imports-in-node-modules-for-browser-bund/77244840#77244840

I should probably figure out how to file this bug as a proper reproducible bug instead.

[LeviPesin]

No, you are using incorrect imports.

Importing import { CSS3DRenderer } from 'three/addons/CSS3DRenderer' is not correct (it works in TypeScript AFAIK but not in JavaScript) -- you should do import { CSS3DRenderer } from 'three/addons/CSS3DRenderer.js, specifying the extension.

There is absolutely nothing wrong with the current exports and they do not contradict what Node.js requires -- the answer on StackOverflow is wrong here. You just should use extensions in your imports.

[marcofugaro]

Already discussed in #24593

Esbuild (which is what Vite is using) is following the ES Modules specification, which requires the .js extension to be specified when importing by default.

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

[CodyJasonBennett]

I still don't see why we can't make such a change that is strictly for such cases with Node ESM. Most packages don't let you import source code via exports, and specify targets like three/nodes, but this leans into implementation details and tribal knowledge of the package. In the future, I'm working towards three/addons in #26910 which will rid of this hazard altogether. This issue is the prime motivation for it.

[pylgrym]

Some moons later, I have finally read up on and grokked(?) all the specs stuff.
What LeviPesin stated, is the truth.
When three.js in their package exports state
subpath: * -> filepath: *,
they are simply stating that things are exported "as-is",
i.e. that a(any) given file is available under its original name.

In the nodejs package spec, this is provisioned for under the anchor #subpath-patterns:
https://nodejs.org/api/packages.html#subpath-patterns

In particular, they are stating that a file like CSS3DRenderer.js will be available under the expected name

'three/addons/CSS3DRenderer.js'

• NOT 'three/addons/CSS3DRenderer' per se (*).

And my confusion stems from interacting with people who rely on various bundler/tooling magic on the javascript side, when handling such imports.
This may all seem obvious to 'people who already know', but when I arrived, I encountered several groups all insisting "No it's the others who are wrong".
That said, I think the whole 'just leave out the suffix' crowd took an unfortunate choice, which causes a lot of problems and and provide questionable gains :-/.

But at least, I have finally understood that it is, of course, not three.js' job to help the extensionless-junkies with their warped desires :-/.

[CodyJasonBennett]

As of r158, you can now import like import { CSS3DRenderer } from 'three/addons'.