fix #334 add esm export

[lhapaipai]

in order to continue the discussion #334

In my opinion, there is an issue with the default export of the package.
According to the package.json

{
  "main": "dist/maplibre-gl.js",
  "type": "module",
}

The maplibre-gl package is using the ESM modules but the output is an UMD file.

If I build an app who follows the esm specification and who wants to import maplibre-gl
The application will apply the esm resolver algorithm

ESM_FORMAT(url)

  Assert: url corresponds to an existing file.
  Let pjson be the result of READ_PACKAGE_SCOPE(url).
  If url ends in ".mjs", then
      Return "module".
  If url ends in ".cjs", then
      Return "commonjs".
  If pjson?.type exists and is "module", then
      If url ends in ".js", then
          Return "module".
      Throw an Unsupported File Extension error.
  Otherwise,
      Throw an Unsupported File Extension error.

the application will retrieve the dist/maplibre-gl.js file but will consider it to be an esm file.
I suggest adding a module entry in the package.json who provides a esm export. By keeping the current main entry, we have a way to easily implement maplibre and with the module entry we allow bundlers (like ViteJS) following the esm specification to find the right export format.

What do you think about that ?

I'm not talking about the isomorphic side dealt with at the end of the discussion #334 which is another discussion.

[HarelM]

Can you please add a change log entry about this?
I have no objections, I'm lost when it comes to all the mess related to importing stuff in js.
If this commit is the standard in the industry I'm all for it...

[github-actions]

Bundle size report:

Size Change: 0 B
Total Size Before: 194 kB
Total Size After: 194 kB

Output file	Before	After	Change
maplibre-gl.js	185 kB	185 kB	0 B
maplibre-gl.css	9.49 kB	9.49 kB	0 B

ℹ️ View Details

No major changes

[HarelM]

Small nitpicking...

[HarelM]

Wrong place, should be one line upwards.

[lhapaipai]

this has been fixed.
But, there is still an issue.
We do not have the named exports when we import Maplibre GL with ESM.

[lhapaipai]

With CommonJS syntax, we can default export an object and its properties are found in the named exports.
Actually

// src/index.ts
const exported = {
    Map,
    NavigationControl,
    //...
};
export default exported;

with rollup became

// dist/maplibre-gl.js
module.exports = {
    Map,
    NavigationControl,
    // ...
};

in your app

import maplibregl from "maplibre-gl"; // ok
import { Map } from "maplibre-gl"; // ok

with ESM we must explicitly define the named export
something like this should be done in index.ts.

// src/index.ts
export { Map } from './ui/map';
export { NavigationControl } from './ui/control/navigation_control';
export default { Map, NavigationControl };
//...

import maplibregl from "maplibre-gl"; // ok
import { Map } from "maplibre-gl"; // ok

I unfortunately do not really know how to operate with the getters setters in src/index.ts.
I'm not very comfortable with these compatibility issues either...
Someone would have any idea ?

[anajavi]

The "module": "dist/maplibre-gl.module.js" is only recognized by bundlers like webpack.

When importing with node an "exports" field should be added. Something like this:

  "main": "./dist/maplibre-gl.cjs",
  "exports": {
    "import": "./dist/maplibre-gl.module.js",
    "require": "./dist/maplibre-gl.cjs"
  },

[lhapaipai]

I totally agree with you @anajavi.
Your solution allows you to obtain a default export but like mine it does not allow named exports with a bundler like Vite and creates 2 almost totally similar files.

[lhapaipai]

I think that by explicitly specifying an esm export without named exports you lose flexibility. I therefore close this request and propose a simpler alternative #635.

[HarelM]

Can you guys check my poposed fixed in the following comment:
#370 (comment)
I think it's a very simple fix that doesn't require a lot of changes...