Provide transpiled ES Module builds for ES5 targets such as Internet Explorer 11

[romanzoller]

This issue came up while trying to integrate @geoblocks/{proj,sources} into a TypeScript / Angular project, and then trying to make it work in Internet Explorer 11 and has already been extensively discussed with @gberaudo.

Problem description

The problem is that the TypeScript compiler (and probably other build tools) will not transpile external dependencies, so a TypeScript project that depends on @geoblocks/proj will end up with ES6 code such as template literals in the build output, which means that it does not work in Internet Explorer 11, and AFAIK there is no way to polyfill things like template literals, computed property names, etc.

Proposed solution

This seems to be a known issue, see e.g. rollup's pkg.module documentation:

Wait, it just means import and export – not other future JavaScript features?

Yes. If you're using things like arrow functions and classes (or more exotic features like decorators and object spread), you should transpile them if you want your library to work in environments that don't support those features. Otherwise, whoever uses your library will have to transpile it themselves, including configuring their transpiler to handle your code, which might involve esoteric transforms and conflicting versions of Babel.

It's a frequent source of frustration. Be a responsible library author and ship code that actually runs in the environments you support!

=> The proposed solution is to provide transpiled ES Module builds for geoblocks using microbundle:

microbundle --format es

See pull requests geoblocks/proj#17 and geoblocks/sources#9. I hope this issue makes the rationale clear and helps for future reference.

Caveats

Ideally, this should make it possible to easily publish CommonJS, UMD, and ES Module builds, as described in the microbundle README (see also Writing a small module in 2018 for more explanations). However, there are currently (at least) two issues:

peerDependencies

In order to have working peerDependencies for CommonJS / UMD, peerDependencies should only be imported through their root module. E.g. if proj4 had an export for somerc in the root module (hypothetically speaking) you could do
import { somerc } from 'proj4';
which would be translated to CJS/UMD as proj4.somerc.
But there is no automatic way to translate an import like import somerc from 'proj4/lib/projections/somerc.js'; (see [1]).

TypeScript

TypeScript currently does not support the .mjs extension, so the non-standard (for modules) .js is used, e.g. dist/proj.js for @geoblocks/proj.
See microsoft/TypeScript#27957

Conclusion

=> The proposed solution is to only provide ES Module builds with the non-standard .js extension for now.

[1]

microbundle errors for CJS/UMD from things like
import somerc from 'proj4/lib/projections/somerc.js';:

No name was provided for external module 'proj4/lib/projections/somerc.js' in output.globals – guessing 'somerc'
No name was provided for external module 'ol/proj.js' in output.globals – guessing 'proj_js'
No name was provided for external module 'ol/proj/proj4.js' in output.globals – guessing 'proj4_js'
No name was provided for external module 'proj4/lib/index.js' in output.globals – guessing 'proj4'
No name was provided for external module 'proj4/lib/projections/lcc.js' in output.globals – guessing 'lcc'
No name was provided for external module 'proj4/lib/core.js' in output.globals – guessing 'proj4$1'
No name was provided for external module 'proj4/lib/projections/utm.js' in output.globals – guessing 'utm'