Roadmap for addons

[LeviPesin]

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

We should make using addons less confusing for the users.

Describe the solution you'd like

I suggest the following road map:

• [x] ~~Make alias three/addons/, pointing to three/examples/jsm/ (https://github.com/mrdoob/three.js/pull/23406)~~,
• [ ] Change the documentation to use word "addons" instead of "examples" and tell only about the alias (https://github.com/mrdoob/three.js/pull/24579),
• [ ] Update manual,
• [ ] Possibly update documentation paths,
• [ ] Move the fonts from examples/fonts, on which addons are dependant (if there are such? Not sure whether it is still the case) to examples/jsm.

After import maps would be supported by Safari and Firefox:

• [ ] Finally drop support for examples/js,
• [ ] Move examples/jsm/ folder to the root of the repo and rename it to addons, making it less confusing for users reading the source code of the addons.

[donmccurdy]

Unfortunately, we may need to have a plan for the possibility that Import Maps never ship in Safari. Import Maps are not listed on the WebKit Feature Tracker, even as "Not Planned". The Import Map specification states —

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track.

I'd love to be wrong, but I don't see much reason to think this will change in the next several years. Perhaps we can express the need to W3C and/or Apple more directly. But in the meantime we are still stuck supporting a difficult mix of things. 😞

[donmccurdy]

We could consider remapping three/examples/js to three/addons as well, I think?

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

Then both of these would work:

// CJS
const GLTFLoader = require('three/addons/loaders/GLTFLoader.js');
// ESM
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

Though if we are getting close to being able to remove examples/js, a new alias for those files is probably not needed.

[marcofugaro]

@donmccurdy The examples/js are not currently in cjs format. They are an iife, supposed to be used via <script src=""></script>. The example you posted would not work.

[donmccurdy]

Oops thanks, yeah. They aren't CJS but are "UMD-like" enough that the usage can be:

// UMD
require('three/addons/loaders/GLTFLoader.js');
const loader = new THREE.GLTFLoader();

// ESM
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const loader = new GLTFLoader();

Though I'd vote for https://github.com/mrdoob/three.js/issues/24593#issuecomment-1238550059. :)

[gkjohnson]

They aren't CJS but are "UMD-like" enough that the usage can be:

If we're going to consider supporting require/commonjs we should do it right. I was going to suggest a pre-publish process that would just be an examples/cjs directory from jsm and never be committed. Then the "exports" section could be included in the "exports" section as you mentioned the maintenance would be low, commonjs would work, there'd be no additional files committed to the project, and we could still commit to removing the /js folder in the long run.

[donmccurdy]

If we're going to consider supporting require/commonjs we should do it right.

We already support the UMD-like path above, A-Frame has been relying on this require() syntax for a few years now. It'd just be an alias for the existing UMD files. But if we hope to move to ESM within a year, I'd rather not touch UMD or CJS further in the meantime.

[gkjohnson]

We already support the UMD-like path above

It's not correct to call that a UMD-like path. UMD is module definition designed to support commonjs, amdjs, and global script definitions. The above version and the examples/js files only supports the global script definitions. The fact that it works with require is entirely an accident and I don't think it's appropriate to export them as commonjs files. Similarly the js files can be used with "import" in order to have the definitions assigned to a global THREE object but it's not "ESM-like" or what anyone would expect.

[donmccurdy]

I look forward to not having to worry about what to call these files after they are gone. 😇

[WestLangley]

Sorry, my incidental clicks changed the original post. I think I restored it.

I thought one could only toggle a check box by "editing" the post... but apparently that is not always true...

[Mugen87]

I think this issue can be closed now since the remaining open points don't need to be changed, imo. Fonts can be kept in examples/fonts, updating the documentation does not work without breaking URLs and it's also not realistic to move examples/jsm to addons/. This would break a lot of paths and URLs so this is not something we can do.

[LeviPesin]

What about build/three.cjs, build/three.js, and build/three.min.js files? Are we going to keep them?

[Mugen87]

We don't need to couple the removal of examples/js with the removal of build files. Probably better to revisit this issue in two or three releases when users have finalized the examples/js migration.

In any event, the removal of build files should be discussed in a separate issue. I'm not sure about the implications for bundlers.