Introducing esm.run - A New-Age CDN for JavaScript modules

[MartinKolarik]

Updated as of Sep 2022:

We are excited to announce a long-awaited feature - improved support for packages distributed as ES modules 🎉

It is currently in beta, which means we encourage you to try it out, but not use it in production applications yet. This issue will cover all technical details and can be also used to provide feedback or report bugs if you find any.

TL;DR

1. Demo and essential information: https://www.jsdelivr.com/esm
2. You can load any ESM file like this:
   • https://cdn.jsdelivr.net/npm/uuid/+esm (default file)
   • https://cdn.jsdelivr.net/npm/uuid/dist/esm-browser/index.js/+esm (explicit file).
3. There's a new domain that you can use for shorter and prettier links. It redirects everything to our main domain and is not meant to be used in production:
   • https://esm.run/uuid
   • https://esm.run/uuid/dist/esm-browser/index.js

How this works

Locating entry points

To find the default file, we use exports, module, and jsnext:main fields from package.json. These fields are currently used by all existing tooling and by most package authors.

Handling imports

Resolving

1. Absolute URLs like https://example.com/foo are always kept in their original form.
2. Relative imports are first resolved via the browser field if it exists (this applies to the entry point as well) and then resolved using node's experimental resolution algorithm, which supports extension resolution and importing from directories that include an index file. The supported extensions are: .mjs, .js, and .json.

Bundling

1. Internal imports (pointing to files in the same package):

   • are bundled with the requested file if they are static, e.g., import foo from './foo.js',
   • are rewritten to their jsDelivr URL if they are dynamic, e.g., import('./foo.js').

2. External imports (pointing to files in other packages):

   • are always rewritten to their jsDelivr URL, whether they are static or dynamic.

This means that one npm package roughly equals one bundle and one HTTP request, which allows good caching and doesn't require too many HTTP requests.

External URLs are always generated with fully resolved dependency versions based on package.json dependencies (or latest if the version is not specified there). This further improves caching and guarantees stable versions even for transitive dependencies.

Performance

• The generated files are automatically minified.
• Source maps are available for easy debugging.
• Once generated, the files are stored in our permanent storage and served from there.
• In supported browsers, HTTP preloading is used to start fetching external static dependencies as soon as possible.

What doesn't work (but may in the future)

• Packages that are written in CJS, or a mix of ESM and CJS. CJS packages are now transformed to ESM.
• Packages that import core node.js modules. Most core node.js modules are now polyfilled.
• Packages that import files in formats other than JS/JSON. CSS is now supported too.
• Packages larger than 50 MiB.
• search on esm.run lists all packages. This will soon be changed to list only the supported ones.

The esm.run domain

This domain is introduced as an easier to remember and type alternative. It doesn't run on our multi-cdn architecture and simply redirects all requests to the main cdn domain, so it's not meant to be used in production.

[Finesse]

Is there a URL option to bundle all imports inside a single file? Comments in files produced by jsDeliver say that Rollup is used so it won't be a problem.

[lubomirblazekcz]

Will the current URL scheme change to me more friendly? Currently what I see in devtools/network is bunch of +esm files

I guess this https://cdn.jsdelivr.net/npm/d3@6.3.1/+esm/d3.js would be better than this https://cdn.jsdelivr.net/npm/d3@6.3.1/+esm

Skypack and esm.sh have similar approach for production urls
https://cdn.skypack.dev/pin/react@v17.0.1-tOtrZxBRexARODgO0jli/min/react.js
https://cdn.esm.sh/react@17.0.1/esnext/react.js

[MartinKolarik]

@evromalarkey I did notice this problem but you can easily configure devtools to show full paths by right-clicking the column:

Alternatively, you could also add the filename as a query string, which we ignore: https://cdn.jsdelivr.net/npm/d3@6.3.1/+esm?d3

[FredKSchott]

Congrats on the release! I've run your benchmarks myself a few times now, and can't reproduce your numbers across a few different devices. Here's what I see on my laptop:

I don't know if this is out of date or just bad, but the data appears outdated across both Skypack and https://esm.run.

Additionally, your benchmark imports are to https://cdn.jsdelivr.net/npm/d3/+esm, and not https://esm.run. That's fine if you want to measure the "optimized" use-case, but then that should really be compared against Skypack's optimized URL as well: https://docs.skypack.dev/skypack-cdn/api-reference/pinned-urls-optimized

Can you update these stats to better represent things to your users?

[MartinKolarik]

Hi @FredKSchott, the performance may of course change over time as each of the services develops. We would have preferred showing realtime results but that wasn't possible so we went with numbers that were accurate at the time this was launched. We'll recheck and update if the results are consistently different now.

Regarding the pinned URLs, those are not functionally equivalent because they lock down a specific version while jsDelivr (even on our primary domain) and unpkg resolve to latest.

[vp2177]

I'm not sure this is the appropriate place to report this, I've tried this service with lit-element and while there are no errors logged, their html function doesn't seem to work.

Here is a repro: https://vp2177.github.io/js-utils/?jsdelivr-lit-element-issue

I have also tried loading lit-element from SkyPack and in that case it works, you can try by uncommenting that import.

[MartinKolarik]

Thanks for the report @vp2177. I don't immediately see where's the problem as L.html returns the correct object but we'll check this further later.

[MartinKolarik]

@vp2177 after closer inspection we found the problem but not yet sure how we'll be able to fix this.

lit-element imports main lit-html file here and it also imports another nested file shady-render.js from lit-html here. The problem is shady-render.js imports the main lit-html file as well.

When we get a request for shady-render.js we include all of its imports, including the main lib-html file (this is by design - as explained in the first post here, internal imports are always bundled).

Then when lib-element imports the main lib-html file in a separate request, it's loaded a second time. This would not be a breaking problem in most cases but the library relies on instanceof checks and those don't work if two versions of the code are loaded.

[MartinKolarik]

@FredKSchott it seems Skypack is now consistently faster than it was before so we decided to update the numbers.

[lubomirblazekcz]

https://esm.run/@fullcalendar/daygrid fails to load, you should check all @fullcalendar plugins though, I think it's because import css (eg. https://cdn.jsdelivr.net/npm/@fullcalendar/timegrid/main.js)

Another problem is https://esm.run/dayjs (works on https://esm.run/dayjs/esm though)

[lubomirblazekcz]

Also I see a potential problem with resolving subfolders (only with production url) when using importmaps

{
  "imports": {
    "dayjs": "https://cdn.jsdelivr.net/npm/dayjs/esm/+esm",
    "dayjs/": "https://cdn.jsdelivr.net/npm/dayjs/esm/+esm/"
  }
}

import isBetween from "dayjs/plugin/isBetween.js" - this wouldn't work

it would work with esm.run url though

{
  "imports": {
    "dayjs": "https://esm.run/dayjs/esm",
    "dayjs/": "https://esm.run/dayjs/esm/"
  }
}

It would work with https://cdn.jsdelivr.net/npm/dayjs/esm/, but that's only because this library has esm version builded on npm. The same problem could be in many other libraries with subfolders.