Use modules everywhere

[tschaub]

This updates our package.json to use modules everywhere.

Server-side use in Node.js

This branch makes it possible for people to use (untranspiled) modules from the ol package directly in Node. Node 12.17 and beyond can import ES modules directly without a flag. It was not possible to import or require (untranspiled) modules from the ol package previously in Node because we don't have a "type": "module" in our published package.json. The default behavior in Node is to treat packages as CommonJS packages, and we use import in our package (which doesn't work in Node with CommonJS modules).

Client-side use with a bundler

This branch doesn't change anything for people who were using import and the ol package with a bundler like Rollup, Parcel, webpack, or esbuild.

See the examples below:

• with esbuild Test with ol@module ol-esbuild#2
• with Rollup Test with ol@module ol-rollup#5
• with Parcel Test with ol@module ol-parcel#1
• with webpack Test with ol@module ol-webpack#3

It is also still possible to use require to import ol modules with webpack, Rollup, etc. I'm not sure if people are doing that, but before and after this change, you can still do things like const Map = require('ol/Map').default;.

Developing in the OpenLayers repo

There are a few things to understand about how this changes scripts and tooling within the OpenLayers repo. By adding "type": "module" to our package.json, we can no longer use require to import *.js scripts in the repo. And the same goes for other dev tooling. We can use require if we need to by using the *.cjs extension on scripts. Alternatively, we can place package.json files with "type": "commonjs" in the repo in directories where we need to author CommonJS modules instead of ES modules. One of these two strategies is required to work with tooling that doesn't yet support ES modules.

Webpack ES module support

As mentioned above, for client-side module bundling webpack works well with ES modules. However, webpack has limited support for ES modules in things like loaders or plugins (see webpack/webpack#13233). We can work around this by naming our custom loader(s) with a *.cjs extension.

Karma ES module support

Karma doesn't support authoring config files as ES modules (see karma-runner/karma#3677). As above, we can work around this by naming our config file karma.config.cjs.

JSDoc ES module support

JSDoc doesn't support authoring plugins or templates with ES modules. Because JSDoc assumes that a template will have a publish.js file, we cannot work around this by renaming our files to have a *.cjs extension. Instead, we add a package.json with "type": "commonjs" to the root of our JSDoc config directory.

Mocha ES module support

For in-browser tests, Mocha works as it did before - with the webpack transpiled modules. This branch also adds the ability to run tests directly in Node. For the Node-based tests, Mocha works with ES modules in single-run mode but not in watch mode (see mochajs/mocha#4374). The tests run fast enough in Node that I don't think this is a problem, but it will be nice when there is a solution.

I've added a test/node directory where we can place tests that are not browser-specific. For now, I've just copied in a handful of the test/browser tests. We could decide that all tests that don't do DOM manipulations should run directly in Node (this is a much simpler setup than the Karma/webpack setup). If others think this is a good idea, I could continue porting some of the existing Karma tests to run directly in Node.

You can try out the results with npm install ol@module.

Fixes #10821.
Fixes #12186.

[tschaub]

I added this to configure the version of Node used in our Netlify builds. If we don't want this file in the repo, we can instead set a NODE_VERSION env var before building the site.

A potential benefit of having this file here is to set the version of Node for others that use nvm.

[tschaub]

Porting over a handful of tests from test/browser to test/node, it looks like the test runtime for the Karma/webpack tests is reduced by about 15 seconds (down to about 2 minutes) and the Node test runtime is about 3 seconds.

[ahocevar]

Very impressive work @tschaub, thanks for your effort on this! I like the idea of having tests that do not rely on the DOM or other browser APIs in test/node. Moving more tests to test/node could also be done in a separate pull request and should not be blocking this, if you want to get this pull request in.