Docusaurus build fails when importing ESM module

[dsawali]

Hello Docusaurus team,

We currently use Docusaurus version 2.3.1 on our project, and it has been working quite well so far.

Recently we updated a dependency that introduces a solid-js dependency on their end, and our Docusaurus builds started to fail. We started digging, and turns out when we update the exports field in that dependency to point to the pre-compiled CJS (instead of the ESM one), it built successfully.

I am aware that this issue #6520 is still ongoing, but am curious to how far the extent of ESM support will Docusaurus have?

But I'm wondering if anyone could help us figure out what exactly might be happening with Docusaurus that doesn't play nicely with some ESM modules. More logs below.

Build errors:

[ERROR] Docusaurus server-side rendering could not render static page with path /docs/upgrading_guide.
[ERROR] Docusaurus server-side rendering could not render static page with path /docs/validators.
[ERROR] Docusaurus server-side rendering could not render static page with path /docs/version.
[ERROR] Docusaurus server-side rendering could not render static page with path /docs/wallet_API.
[ERROR] Docusaurus server-side rendering could not render static page with path /docs/wallets.
[ERROR] Docusaurus server-side rendering could not render static page with path /docs/web3js_taquito.

...

TypeError: (0 , server_namespaceObject.template) is not a function
ReferenceError: Cannot access 'Feedback_AddFeedback' before initialization
ReferenceError: Cannot access 'Feedback_AddFeedback' before initialization

...

[WARNING] {"moduleIdentifier":"/Users/.../node_modules/@airgap/beacon-ui/dist/esm/index.js","moduleName":"../node_modules/@airgap/beacon-ui/dist/esm/index.js","loc":"155:30-38","message":"export 'template' (imported as 'template') was not found in 'solid-js/web' (possible exports: Assets, Dynamic, ErrorBoundary, For, Hydration, HydrationScript, Index, Match, NoHydration, Portal, Show, Suspense, SuspenseList, Switch, addEventListener, createComponent, delegateEvents, escape, generateHydrationScript, getAssets, getHydrationKey, hydrate, insert, isDev, isServer, mergeProps, pipeToNodeWritable, pipeToWritable, render, renderToStream, renderToString, renderToStringAsync, resolveSSRNode, spread, ssr, ssrAttribute, ssrClassList, ssrElement, ssrHydrationKey, ssrSpread, ssrStyle, stringify, useAssets)","compilerPath":"server"}
[WARNING] {"moduleIdentifier":"/Users/.../node_modules/@airgap/beacon-ui/dist/esm/index.js","moduleName":"../node_modules/@airgap/beacon-ui/dist/esm/index.js","loc":"156:27-35","message":"export 'template' (imported as 'template') was not found in 'solid-js/web' (possible exports: Assets, Dynamic, ErrorBoundary, For, Hydration, HydrationScript, Index, Match, NoHydration, Portal, Show, Suspense, SuspenseList, Switch, addEventListener, createComponent, delegateEvents, escape, generateHydrationScript, getAssets, getHydrationKey, hydrate, insert, isDev, isServer, mergeProps, pipeToNodeWritable, pipeToWritable, render, renderToStream, renderToString, renderToStringAsync, resolveSSRNode, spread, ssr, ssrAttribute, ssrClassList, ssrElement, ssrHydrationKey, ssrSpread, ssrStyle, stringify, useAssets)","compilerPath":"server"}
[WARNING] {"moduleIdentifier":"/Users/.../node_modules/@airgap/beacon-ui/dist/esm/index.js","moduleName":"../node_modules/@airgap/beacon-ui/dist/esm/index.js","loc":"157:27-35","message":"export 'template' (imported as 'template') was not found in 'solid-js/web' (possible exports: Assets, Dynamic, ErrorBoundary, For, Hydration, HydrationScript, Index, Match, NoHydration, Portal, Show, Suspense, SuspenseList, Switch, addEventListener, createComponent, delegateEvents, escape, generateHydrationScript, getAssets, getHydrationKey, hydrate, insert, isDev, isServer, mergeProps, pipeToNodeWritable, pipeToWritable, render, renderToStream, renderToString, renderToStringAsync, resolveSSRNode, spread, ssr, ssrAttribute, ssrClassList, ssrElement, ssrHydrationKey, ssrSpread, ssrStyle, stringify, useAssets)","compilerPath":"server"}

[slorber]

It's hard to help on these issues without a small repro unfortunately (using local code, not importing third-party libs).

Usually ESM libs can work if you use dynamic imports

[ilg-ul]

Usually ESM libs can work if you use dynamic imports

I heard this several times, but I fail to see how this can be useful. From my experience, the reason for a package to be ESM only is having ESM only dependencies (otherwise the package can be easily kept or CJS or made dual). So using dynamic imports to include a package that itself imports other ESM modules gets you only one step further, but does not solve the problem. :-(

[slorber]

the reason for a package to be ESM only is having ESM only dependencies

Some devs will push the ecosystem toward using ESM, and only publish newer versions of their packages as ESM. That's just a fact, they don't have to agree with your reasoning. If you want to integrate with such a package you have to play their rules and use dynamic imports.

MDX 2 is such a package, and you'll see that I actually need to use dynamic imports in my PR: #8288

but I fail to see how this can be useful

🤷‍♂️ it's useful because it works.

The other possible solutions:

• convince the author to publish to CJS again (they probably won't do that)
• fork the package and add CJS support yourself

---

So using dynamic imports to include a package that itself imports other ESM modules gets you only one step further, but does not solve the problem. :-(

The "step further" is working, and permits running the code, so for me it indeed solves a problem.

If this didn't work we'd have to migrate to ESM at once for the whole project instead of migrating incrementally. Upgrading to MDX 2 is already complex, so if I had to bring full ESM support at the same time that would lead to a huge messy PR.

[ilg-ul]

If that worked, great for you! And for us, who use your project! :-)