Three.js: JSM: Documentation for importable examples

[donmccurdy]

It'd be great to have 'how to import this' near the top of documentation for example files, as we add support for them. Like:

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

We get enough questions here and in the forums where people are surprised something isn't part of the core library, and this might help with some of that.

[Mugen87]

There is also: https://threejs.org/docs/index.html#manual/en/introduction/Import-via-modules

Notice the section at the end of the page:

Currently it's not possible to import the files within the "examples/js" directory in this way. This is due to some of the files relying on global namespace pollution of THREE. For more information see

How about adding information about JSM right there?

[donmccurdy]

Definitely adding it there would make sense. 👍 I would also be glad to see it on per-file documentation, as the fact that a given file is not part of the core library is a common source of confusion.

[mrdoob]

You know what... I think we should start converting all examples to <script type="module"> 😁

Compatibility seems to be there: https://caniuse.com/#feat=es6-module

We just lose IE11. But we kind of lost it already when using promises in GLTFLoader and using the loader in many of the examples.

We may want to have a couple of examples using nomodule for testing IE11 though.

[donmccurdy]

I'm happy with converting examples to ES modules gradually, but just to mention the option – all of the GLTFLoader examples can be made IE11-compatible just by adding a single script tag to the example with a Promise polyfill.

As far as I can tell, 'polyfilling' modules for IE11 is not so simple and would result in code that doesn't demonstrate real-world use.

That being the case, do we still want to convert example HTML files to use ES modules?

[garyo]

Not that my opinion necessarily carries any weight, but as a new three.js user, I'm writing 100% typescript and ES modules. I expect most new projects are at this point. Webpack and other tools can transpile back and add some polyfills for older browsers when needed (I think a lot of people care less & less -- YMMV).