Docs: Update 'Installation' section for ES Module migration.

[donmccurdy]

As promised in #18749, I've drafted a post explaining the decision to remove the examples/js folder and encouraging users to start using ES modules.

The forum post makes references to an "installation" guide, explaining in more detail how to use ES modules in various situations. I think that guide should live in the three.js website's documentation, replacing the current "Import via modules" section, which this PR includes.

• Announcement on forums: (Draft) Deprecation of global <script> and CommonJS imports
• Installation: (this PR) https://raw.githack.com/donmccurdy/three.js/docs-installation-es-modules/docs/index.html#manual/en/introduction/Installation

The documentation would also benefit from #18778, so that users can easily tell when they're looking at documentation for a file that needs to be imported from three/examples/jsm, but neither the forum announcement nor this PR depend on it.

[WestLangley]

Nit. I still cringe when I see three.js capitalized, though -- even at the start of a sentence.

[donmccurdy]

Fixed!

[Mugen87]

@mrdoob Is it okay to merge this PR? I would love to see the updated docs and the new forum topic so it can use it as a reference during user support.

[mrdoob]

Thanks!

[donmccurdy]

@mrdoob and @Mugen87, what do you think about the draft announcement? Do we want to post something like that on the forums, or in a new GitHub issue? My thinking would be to add a link to the announcement (wherever it is) in the deprecation messages of each file in examples/js, so that users have a centralized place to give feedback or ask questions.

[mrdoob]

Thanks a lot for writing that!

I think we can add that page to the docs, and include the link in the current deprecation message.

We may want to mention import maps at the end of the article. The fact that we're aware that the current ergonomics have issues, but that we're hoping to be able to leverage import maps in the near future.

[mrdoob]

We may also want to mention import maps in the Installation page too?

[donmccurdy]

A possible advantage of a forum thread or a GitHub issue (compared to a page in the docs) is that it becomes the primary place to ask questions or find workarounds for common issues. Otherwise people will probably start new issues for each question. Do you prefer one way or the other?

Mentioning import maps on the Installation page makes sense, yes.

[mrdoob]

Yeah, that's a good point. A forum post would work better 👌

[Mugen87]

I vote for the forum! 😊

[donmccurdy]

Suggested addition to the Installation docs, below. The benefit of import maps is a bit nuanced — if you haven't had any issues with the relative ../../build/three.module.js references in examples/ files, it may not matter to you. So I think we may want to put this section in the docs but not the blog post. Does that sound right, or have I missed part of the objectives for import maps? I am assuming that when import maps are broadly supported we would replace those relative imports with import { ... } from 'three', and do the same in all of our examples, so that everything uses a consistent pattern.

---

Compatibility

Import maps

Imported paths differ when installing from npm, as compared to installing from static hosting or a CDN. We're aware that this is an ergonomic issue for both groups of users. Developers with build tools and bundlers prefer bare package specifiers (e.g. 'three') rather than relative paths, and files in the examples/ folder use relative references to three.module.js that don't follow this expectation. Those who do not use build tools — for fast prototyping, learning, or personal preference — may similarly dislike those relative imports, which require certain folder structures and are less forgiving than a global THREE.* namespace.

We hope to remove these relative paths when import maps become broadly available, replacing them with bare package specifiers to the npm package name, 'three'. This matches build tool expectations for npm packages more closely, and allows both groups of users to write exactly the same code when importing a file. For users who prefer to avoid build tools, a simple JSON mapping can direct all imports to a CDN or static file folder. Experimentally, you can try using simpler imports today with an import map polyfill, as shown in our import map example.