How does esm.sh convert these ESM modules from CJS modules?

[junyin-ms]

First of all, this is awesome work and website! For the first time, I am able to use react in non-bundled true ESM modules.

I am curious how these ESM modules are generated, since for example, react has officially publishes only CJS and UMD format. I looked at the MJS file and found the following header, which led me to investigate ESBuild.

/* esm.sh - esbuild bundle([email protected]) es2022 development */
var __create = Object.create;
var __defProp = Object.defineProperty;

However, when I tried to run ESBuild with --format=esm on react-dom.development.js, it gave the following error:

▲ [WARNING] Converting "require" to "esm" is currently not supported [unsupported-require-call]

    node_modules/react-dom/cjs/react-dom.development.js:26:22:
      26 │           var React = require('react');
         ╵                       ~~~~~~~

▲ [WARNING] Converting "require" to "esm" is currently not supported [unsupported-require-call]

    node_modules/react-dom/cjs/react-dom.development.js:27:16:
      27 │ var Scheduler = require('scheduler');
         ╵                 ~~~~~~~

This is different than the react-dom.development.js hosted on esm.sh, which has successfully converted require in CJS to import in ESM:

/* esm.sh - esbuild bundle([email protected]) es2022 development */
import * as _1$ from "/v115/[email protected]/es2022/scheduler.development.mjs";
const __1$ = _1$.default??_1$;
import * as _2$ from "/stable/[email protected]/es2022/react.development.mjs";
const __2$ = _2$.default??_2$;

I would like to learn how I can convert CJS modules which resides in my local node_modules directory to ESM, without bundling. Ideally the tooling can be smart enough to walk down the import tree to convert dependent CJS to ESM as well so it is purely in ESM.

Thank you!

[ije]

Thanks!

covert CJS to ESM is not that easy, there are a lot of edge cases if you want every packages work correctly. But the basic approach is using the esbuild plugin system: remark the require calls as external then replace them manually with the esm syntax.

the hardest part is looking up those external requires in the output code, you can check the source code shows how we handle it.

esm.sh/server/build.go

Line 794 in a546b8b

cjsContext = bytes.HasSuffix(p, []byte{'('}) && !bytes.HasSuffix(p, []byte("import("))

[junyin-ms]

Thank you @ije for your prompt reply!

It is such a disappointment that even though ESM has been supported in major browsers for over 5 years, the community still largely depends on CJS, AMD and UMD in the node.js ecosystem. Even famous libraries like react have not officially published ESM to NPM yet. And we have to do all the hard work because of this.

The source code you pointed me looks quite complex and long. What ESBuild plugin do you use to replace the require statement with import? Is your code fully automated or do you need a manual review and edit after the JSM is generated with your code? Given that I might not be able to understand the code in a reasonably short time, I see my options to use ESM in my project are:

1. Skip the details, run the tool. Is it possible for you to warp the complex logic into a command line tool, so I can run against an entry CJS module in my local node_modules directory?
2. Skip the details, download from esm.sh website. Is there an automatic way to download an entry JSM and its dependencies? It would be tedious to analyze the dependencies and then download them one by one manually. Further, I need to open these JSM and update the import path like "/v112/[email protected]/es2022/scheduler.development.mjs" to fit my local directory structure.
3. Or do you have any better suggestion?

Thank you!

[dburles]

I share your frustration with React! I've been thinking the same thing for a long time. It would be amazing if we had a cli version where we could just install packages locally.

[ije]

what if your can install the esm version of a cjs-only package via npm CLI? e.g. npm i https://npm.esm.sh/[email protected]

[dburles]

@ije That would be perfect.

[dburles]

Hey @ije, still super interested in this idea. Do you have an idea how difficult it would it be to create?

[noherczeg]

One of the "funniest" things when you try to convert peerDeps to standalone ESM modules is that e.g.: esbuild generates different imports in userland code when we external deps compared to what it does when we define manualChunks. If you combine this fact with some sub-optimally written libraries which have "hidden" imports like react and react/jsx-runtime, you can run into a whole lot of trouble.

This aside, I'd also love a cli a tool which can do something like what esm.sh does, but on-prem, locally. (on NodeJS)