Continue support for JS libraries alongside ES6 JSM libraries

[Bug-Reaper]

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

I believe it is good library hygiene to support both module and classic static file imports.This keeps the library accessible to a wider group of developers and allows developers to use their preferred style.

Personally I really try to avoid using modules in general, I like projects that are static files with classic simple JS file includes. Maybe I'm just a weirdo but I really hate how far frameworks unnecessarily abstract you from things and how much they re-invent wheels or otherwise black-box you. I know you can use modules without any frameworks, however module includes are less intuitive then traditional JS includes, they often have failed me when trying to use them within a static file setup.

Using ES6 Modules are not ideal for every deployment, though they are certainly a welcome addition. I teach many new programmers threejs because I love the library and IMO it is a great and satisfying way to get into programming. It is a lot easier to teach people basic vanilla CSS/JS/HTML without also shoving the entire node/npm + framework stack down their throat at the same time. Static libraries are simpler to use/understand and keep the barrier to entry low here.

Stylistically, I also prefer overloading THREE with additional functionality instead of adding new named functions that float around freely. Though this is obviously preference.

Describe the solution you'd like

Perhaps I can better answer this after getting a bit more information about why the decision was made to transition to modules only, but I'll take a stab at it.

The documentation addresses that ES6 modules may not work in every situation and for those situations it suggests using a bundler such as browserify/rollup/webpack/parcel etc....

My solution would be have an automatic ES6 bundler script go through the modules in /examples/jsm to generate /examples/js non module versions. This way developers no longer need to worry about making changes in two places and can continue to enjoy using the JS non module versions and global var import style if they like.

This automatic generation of JS non module files could be done as part of the build process or be a command in the package.json someone could run manually. Though I'd opt for automatic generation.

Creating this automation or otherwise maintaining the JS non module versions of this library is something I can donate my time for. If the reasoning behind jumping to ES6 only is not just removing the need to update two parallel version of the same thing manually, I'd love to discuss other solutions to address those concerns as well.

Describe alternatives you've considered

The obvious other consideration would be to leave things as is and continue maintaining JS and JSM versions of all libraries. Though considering the announcement these are being deprecated, I find this somewhat unlikely. But I'd be happy to take on responsibility for making sure JS libraries stay up to date with their JSM counterparts manually if we decide to go this route.

Additional context

Much love to this library and everyone that contributes either in code or by reporting/discussing issues.

[gkjohnson]

It is a lot easier to teach people basic vanilla CSS/JS/HTML without also shoving the entire node/npm + framework stack down their throat at the same time. Static libraries keep the barrier to entry low here.

Just to clarify the example js modules as maintained in this project do not require node, npm, or any build framework to use. They can be used as statically served files just like the old global imports. They just require the es6 import syntax in order to use but that will work in all modern browsers.

[Bug-Reaper]

Just to clarify the example js modules as maintained in this project do not require node, npm, or any build framework to use. They can be used as statically served files just like the old global imports. They just require the es6 import syntax in order to use but that will work in all modern browsers.

Thank you for the clarification! That is indeed a good point!
I believe:

<script type="module">

  import { OrbitControls } from 'https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js';

  const controls = new OrbitControls();

</script>

is perhaps less intuitive and harder to understand for newcomers than:

<script src="https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js">

Also, correct me if I'm wrong, the modules do not create globals for use in later scripts? So there would be no easy way to use THREE.js /example/jsm files outside of a module?

Personally I've had issues importing modules this way in static files even when using modern web browsers. Docs also seem to indicate using a bundler may be required for common js functionality. Though I should really experiment further with THREE.js modules specifically to get better insight here.

If we can continue to support the JS versions easily with an automated ES6 bundler script which goes through the JSM versions, I think this is worth doing.

[DefinitelyMaybe]

wait a sec... we've still got:

<script src="path/to/local/build/three.js"></script>

as oppose to:

<script type=module src="path/to/local/build/three.module.js"></script>

The first is a static script that can be used as per the old-global-way within someone's html... right? What was the thing you couldn't do anymore after a transition to ES6?

[Mugen87]

<script type=module src="path/to/local/build/three.module.js"></script>

I don't think it makes sense to import three.module.js that way. It should be:

<script type="module">

    import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.121.1/build/three.module.js';

   // app code

</script>

[Bug-Reaper]

The first is a static script that can be used as per the old-global-way within someone's html... right? What was the thing you couldn't do anymore after a transition to ES6?

I believe you're correct. If I understand correctly the plan is to still include a "/build/three.js" in addition to the "/build/three.module.js".

However, currently using any of the utilities in "/examples/js" folder will warn you they're deprecated and soon to be removed in favor if "/examples/jsm" ES6 module versions. Which means you'd no longer be able to use the old global style of implementation.

If we can do so easily, I believe it makes sense to continue supporting /examples/js by automatically generating them via a ES6 bundler script as part of the build process.

[Mugen87]

If I understand correctly the plan is to still include a "/build/three.js" in addition to the "/build/three.module.js".

Yes. However, it's questionable if this approach does make sense. When examples/js is removed, there are only a few use cases left where three.js and three.min.js are still useful.

It would be actually beneficial to remove three.js and three.min.js since it would allow us to change the main entry point of the npm package, see #19575.

If we can do so easily, I believe it makes sense to continue supporting /examples/js by automatically generating them via a ES6 bundler script as part of the build process.

The idea is to move examples/jsm to more modern JavaScript language features like classes. Since examples/js should still work with older browser, it would be necessary to configure a new (examples) build with code transpilation features. Besides, we would still keep the duplicate code base (examples/js vs examples/jsm) which is in my point of view a bad approach. It makes maintenance more complicated.

I believe the user has to take care of ES6 to ES5 conversion if required. Same for code minification or other build-related tasks.

[devingfx]

I believe you're correct. If I understand correctly the plan is to still include a "/build/three.js" in addition to the "/build/three.module.js".

True

The problem with filles from /examples folder is that you need to use files from /examples/js when you used /build/three.js and files from /examples/jsm when you used /build/three.module.js , aka keep consistency in loading method.

Why? Because when using module imports the main THREE object is no more a plain js object THREE = {} but instead an internal browser's module object that is sealed (not extendable), therefore, files from /examples/js that tries to write a new property in THREE object fails.

So you can't mix import * as THREE from '/build/three.module.js and THREE.WhateverExample = function() ...

One possible way is to change the name of imported lib to anything else than THREE and re-create a plain js THREE global object for examples to be written in it...

This is typically the problem of

traditional JS includes

that polutes global space naming, and because you can't modify names into the loaded file you may get errors like that...
On the other hand, with modules, the user gain the power of naming during the import and it's no more the author of the lib that choose the resulting name...

ex:

<script>
// a script you can't modify already use the name THREE
var THREE = document.getElementById('div-nb-3')
</script>

<script type="module">
import * as foo from '/build/three.module.js'

THREE.appendChild( new foo.WebGLRenderer().domElement )
</script>

[Bug-Reaper]

@Mugen87 You're 100% right. If we ditch the /examples/js we might as well ditch the three.js & three.min.js as they're essentially incompatible with any of the add-on modules. Their use case would be niche and this is almost guaranteed to create confusion.

@devingfx You're right that modules have advantages and eliminates potential global name conflicts. In years of use I've never had anything conflict with the THREE global variable and I think this is an unlikely scenario but your point is technically correct.

which is in my point of view a bad approach. It makes maintenance more complicated.

I believe the user has to take care of ES6 to ES5 conversion if required. Same for code minification or other build-related tasks.

@Mugen87 Is it really that terrible to maintain a traditional js include which uses a global var in addition to a module? Many libraries support both and from what I can tell the traditional JS version is often just as popularly used as the module version counterparts. Both have advantages/disadvantages and some of that boils down to preference. Is it not good to give developers the option of using a library in a non-module context?

I'm willing to take care of creating/testing the necessary code transpilation features to automatically generate three.min.js, three.js and /examples/js from the three.module.js and /examples/jsm. After the transpilation workflow has been finessed, it may require some minimal maintenance but it != maintaining two parallel versions. For the most part code would only be needed to be updated on the module files and only occasionally would you need to fix some transpilation fuckup.

I have enough projects that rely on the traditional global syntax and includes that I'm going to be doing the work for automating the transpilation of the modules anyways. I think at the very very least we could include a command in the package.json and call it "legacy-build" which transpiles the modules into three.min.js, three.js and /examples/js which behave similar to the original files now. These files don't even have to be committed to the repo or created by default. We could also warn they're for legacy support, they're not guaranteed to work, we suggest using modules instead etc...

Realistically though I think it makes more sense keep them in the repo and simply have them be automatically generated via transpiling on build.

[DefinitelyMaybe]

a command in the package.json and call it "legacy-build" which transpiles the modules

seems reasonable. wasn't babel merged in recently? so I think this might be doable as is

edit: to clarify, not to have said new command to be run by anyone except the users which want said build

[gkjohnson]

Is it really that terrible to maintain a traditional js include which uses a global var in addition to a module?

I think the complexity of maintaining this is being under estimated. Unfortunately I don't think it's so simple with the way examples are set up in the project.

Let's look at GLTFLoader as an example. Right now all of GLTFLoader is contained in a single file which makes it easy to include at the top of an HTML file. One of the benefits of modules is that some of the larger files can be broken out into separate files that GLTFLoader can import as dependencies. What should the built global script include look like once GLTFLoader depends on four external files some of which are shared? Will users of the built global scripts now have to include all of those example js files individually? Or will some files be bundled together which would require manually maintaining a list of files that are okay to bundle together and which are not?

I think the only really set and forget case is bundling all of the example js files into a single monolithic blob which I don't think is reasonable. I think with any of these solutions there'd be some other release and documentation overhead, as well.

Perhaps there's a better way to do it but when I tried to make a rollup build that retained backwards compatibility or at least a consistent structure to the existing js files these are the issues I ran in to.

[RemusMar]

If I understand correctly the plan is to still include a "/build/three.js" in addition to the "/build/three.module.js".

Yes. However, it's questionable if this approach does make sense.
When examples/js is removed, there are only a few use cases left where three.js and three.min.js are still useful.

@Mugen87 @mrdoob

Michael,
In fact to keep "three.min.js" for at least 2 more years is a MUST.
Not because all my samples are based on it.
But because many thousands of files and Google top dogs are based on it!
Example: https://www.google.com/search?source=hp&q=webgl+benchmark

On the other hand, from my point of view, "three.min.js" means faster development and testing.
Not to mention that it works offline and you don't need localhost.
Just put all the files in a folder somewhere, use Firefox and double click the HTML file.
I always loved that for development!

Ricardo should also think about all of these.
cheers

[Mugen87]

The removal of three.js and three.min.js is something that can be discussed and planned when examples/js is gone. It was just important for me to highlight their lost in significance when you can't import files from examples/js anymore.

[Bug-Reaper]

I think the complexity of maintaining this is being under estimated. Unfortunately I don't think it's so simple with the way examples are set up in the project.

I really like the points you go on to bring up. There's absolutely unforeseen complexity in bundling and the example of nested modules is a good one. To your point, I think we can come to sensible decisions about how to handle bundling nested modules when that time comes. I'm not saying a bundler script will be a set it and forget it situation, merely that it will be lower maintenance.

If the time comes where it's too hard to maintain we can always drop it, but I think it's silly to discount trying on account of problems we don't have yet. It will be easiest to implement now while we still have 1 to 1 parity between /examples/jsm and examples/js. We likely won't be massively re-organizing the /example/jsm module hierarchy and I think we can make incremental updates to the bundler when we do. I'm going to go ahead and start working on proof of work for this (with babel because it's already added?) to put my money where my mouth is as they say.

To Mugen's point, this would help keep some relevancy to three.js and three.min.js while we continue to maintain them. It could also help the hundreds of sites that might be looking for an update compatible with their non module based THREE implementation. The refactoring of a THREE project to use modules can be quite extensive even if you know what you're doing.

[Mugen87]

I can't speak for the other collaborators but I will not change my mind on this topic. I vote to delete examples/js with the December release in 2020 as discussed and committed here #18749.

[RemusMar]

I vote to delete examples/js with the December release in 2020 as discussed and committed here #18749.

I don't have any problem with that.
As long as "three.min.js" is available for another couple of years ...