EsModules

[Quafadas]

First step to closing #638 .

A publish local off this branch actually seems to work.

• [x] Unbreak broken tests
• [x] Add new tests
• [x] Get CI green

[Quafadas]

I can't understand the failing test on windows :-(.

[Quafadas]

This seems to be easier than expected. I think this PR would actually be viable which was a surprise for me.

If it were to get merged and it maintainers agreed, I'd try and follow it up with two more PRs

• enabling SmallModulesFor
• an EsImportMap rewrite-esmodule-imports-at-link-time functionality...

[nguyenyou]

Thank you very much for working on this 🤩

[Quafadas]

@tgodzik Hi Tomasz, I think this would be ready for a discussion ... it takes the first step toward making scalaJS EsModules powerful in mdoc.

This PR modifies only Mdocs CLI. As far as I can tell, this PR works in the sense that it emits ESModules, and those modules work with docs own static server in watch mode. If you agree with the direction of travel, I'd attempt to follow it up with two more PRs

• enabling SmallModulesFor
• EsImportMap rewrite-esmodule-imports-at-link-time functionality...

I think that would enable mdoc to provide documentation for a broad array of scala JS projects.

[Quafadas]

But, out of curiosity, why is it beneficial over using normal scripts, especially in case of mdoc?

Well, the use case isn't 100% proven, but basically; EsModules allow importing other EsModules.

To take an example - the excellent laminar shoelace library, its documentation is (as far s I can tell) a full-blown-full-stack sbt+vite+fly.io app. As things stand, I think it has to be that, because you gotta resolve the npm shoelace dependancy then build and bundle. https://github.com/raquo/laminar-full-stack-demo/blob/acc41bd63745de786d20715934169abe147853a7/client/package.json#L28

The barrier to entry there, is actually pretty high - full stack scala plus a bundler (vite => entire nom ecosystem) plus setup cloud infrastructure.

EsModules allow importing other EsModules.

Party trick - in browser referencing a CDN. https://github.com/Quafadas/ShoelaceSansBundler/blob/3bd156fd55884f71aeb00cb967b308e9ecf99772/importmap.json#L3

In isolation, I agree this PR is not that useful :-) ...

My hope, if you were comfortable with the direction of travel, is that I would then follow up this PR with something like this; https://github.com/VirtusLab/scala-cli/pull/2737

for mdoc.

The hypothesis is then, that something like laminar-shoelace or my own (lower profile :-) ) experiments, can be easily documented (via markdown - mdoc) and published in a static site (e.g. on GitHub pages - the browser just needs to hit up the CDN) - and they can depend on an arbitrary EsModule dependancy - without needing the bundler.

The remaining problems, are already quite well solved...

... and without a bundler or backend! Said differently, I believe this could (no guarantees) ultimately crush the barrier to entry of documenting scala-js libs.

[tgodzik]

That sounds awesome! It would be cool if you could later add a bit of documentation to mdoc if it pans out.