v135 / Introducing esm.sh/run

🎉🎉🎉 Introducing esm.sh/run, a 1KB script allows you to write jsx/tsx in HTML without build step!

Installation

<script type="module" src="https://esm.sh/run"></script>

Usage

The script allows you to add <script> elements with jsx/typescript in your HTML, for example:

<script type="text/babel">
  console.log("esm.sh run!" as string)
</script>

Supported types:

• text/babel (recommended, highlighting is working in vscode)
• text/jsx
• text/ts
• text/tsx

Using Import Maps

esm.sh run supports import maps, it even works in outdated browser that doesn't support the feature.

<script type="importmap">
  {
    "imports": {
      "@jsxImportSource": "https://esm.sh/[email protected]",
      "react-dom/client": "https://esm.sh/[email protected]/client"
    }
  }
</script>

The special @jsxImportSource in the imports is using for JSX transform, you can alternate it to your preferred runtime, for example https://esm.sh/[email protected].

How it Works?

After the page loaded, the run script computes the hash of the source code of non-javascript <script> elements as the cache key, if the cache exists then run it, otherwise sends the source code to esm.sh build API and stores it in the cache system.
The cache system includes two iters of storage, are the localStoarge and Cloudflare Edge cache, to make the compiled JS load fast!

Limitations

There are some limitations you need to be aware of:

• the build task is slower than local babel/swc/esbuild (only happens when the source code has been changed)
• 60 build tasks pre minute is allowed

Try it Online

👉 Play with TailwindCSS ⏎

---

Other changes

• worker: Use raw.esm.sh hostname for ?raw option
• Add ?no-bundle option
• Support esm.sh field in package.json
• Fix sub-module resolving (close #754, #743)
• Upgrade esbuild to 0.19.7

v134

esm.sh v134 mainly includes some bugfix patches. And now you can add allowList option to serve specific packages on you self-hosting esm.sh server. (Thanks @olekenneth for contributing to this!)

Changelog

• Add transformOnly option for build api
• Add allowList in config (#745 by @olekenneth)
• Improved Deno CLI (#742 by @Kyiro)
• Worker: fix dist version lookup
• Fix exported names from a dependency (close #729, #750)
• Fix: write .npmrc file if NpmRegistry is set (close #737) (#751 by @edeustace)
• Upgrade esbuild to 0.19.5

v133

In v133, we introduced the ?raw mode that returns the raw JS files and fixed a bunch of bugs.

Escape Hatch: Raw Source Files

In rare cases, you may want to request JS source files from packages, as-is, without transformation into ES modules. To do so, you need to add a ?raw query to the request URL.

For example, you might need to register a package's source script as a service worker in a browser that does not yet support the type: "module" option:

await navigator.serviceWorker.register(
  new URL(
    "https://esm.sh/[email protected]/playground-service-worker.js?raw",
    import.meta.url.href
  ),
  { scope: '/' }
);

You may alternatively specify an &raw extra query after the package version:

<playground-project sandbox-base-url="https://esm.sh/[email protected]&raw/"
></playground-project>

so that transitive references in the raw assets will also be raw requests.

Thanks @johnyanarella for contributing to this.

Changlog:

• Add ?raw to support requests for raw package source files (#731 by @johnyanarella)
• Add global setMaxListeners to node:events polyfill (#719)
• cjs-lexer: resolving error now doesn't break build (close #738)
• Fix cwd method of node:process polyfill (close #718)
• Fix applyConditions function use node condition for browser (close #732)
• Fix *.css.js path (close #728)
• Fix some invalid require imports (close #724)
• Fix relative path resolving of browser in package.json
• Upgrade esbuild to 0.19.4

v132

In v132, no features are added but some bugs have been fixed.

Changelog:

• Resolve node internal modules when ?external=* set (close #714)
• Fix builds with bigint and top-level-await for all targets (close #711)
• Fix node:process ployfill module mssing the hrtime method
• Fix docker image missing git command
• esm-worker: add varyUA option for polyfill modules

v131

In v131, we improved the /build API to avoid duplicated builds of same input code, and fixed some bugs:

• Add a cache layer for the /build API
• Fix dts transformer resolver ignoring *.mjs url
• Fix ?external option ignoring sub-modules
• Use raw order of the exports in package.json (close #705)
• Redirect old build path (.js) to new build path (.mjs) (close #703)
• Upgrade esbuild to 0.19.2

v130

esm.sh v130 improves the esm-cjs-lexer to get correct exports of a minified UMD module, this can fix error "missed named exports" of some cjs only packages. The great change was contributed by @lewisl9029, huge thanks ❤️

Changelog:

• esm-cjs-lexer: support minified UMD exports (#689 @lewisl9029)
• Fix sub .mjs module (close #691)
• Fix playground (https://code.esm.sh) editor don't load language workers
• Fix ?bundle mode ignores node_process.js (close #694)
• Upgrade @types/react@18 to 18.2.15
• Upgrade esbuild to 0.18.17

v129

esm.sh v129 mainly inclueds some bug fixs:

• BREAKING: Remove X-Esm-Deps header (close #683)
• Sort exports of package.json when looping (close #683)
• Don't replace typeof window for deno target (close #681)
• Don't replace node global variable for ?target=node
• Fix dts transformer (close #670)
• Fix depreacted message with "
• esm-worker: Fix cacheKey with X-Real-Origin header

v128

In v128, we added an official Docker image to allow you to self-host esm.sh more easily (This is based on johnpangalos/docker-esm-dot-sh by @johnpangalos, thank you!).

docker pull ghcr.io/esm-dev/esm.sh

More usage check HOSTING.md

For Deno users, we upgraded stableBuild to latest(v128) this may break your deno.lock.

Changelog

• Add official Docker image: https://ghcr.io/esm-dev/esm.sh
• Fix missed ?external for deps
• Fix duplicate Access-Control-Expose-Headers headers
• Fix dts transform for imports with both default and named imports (#675 by @hayes)
• Don't bundle dynamic imports
• BREAKING Upgrade stableBuild to v128

v127

In v127, we improved the network waterfall by adding the dependency imports of current module in the entry module (aka. preload).

For example: https://esm.sh/[email protected]

import "https://esm.sh/stable/[email protected]/es2022/react.mjs";       /* Added in v127 */
import "https://esm.sh/v127/[email protected]/es2022/scheduler.mjs"; /* Added in v127 */
export * from "https://esm.sh/v127/[email protected]/es2022/react-dom.mjs";
export { default } from "https://esm.sh/v127/[email protected]/es2022/react-dom.mjs";

For framework authors, esm.sh provides an extra X-Esm-Deps header that allows you to get those preload import urls.

const res = await fetch("https://esm.sh/[email protected]")
console.log(res.headers.get(`X-Esm-Deps`)?.split(", "))

Changelog:

• Add preload imports
• Add modern-normalize to the cssPackages
• Fix subpath not be resovled with ?alias (close #671)
• Fix dts transformer for "*.d" path imports (close #660)
• Fix source map mappings (close #668)
• CLI: Fix update failure caused by gh module (#661 by @lifegpc)
• Upgrade esbuild to 0.18.10

v126

• breaking: the esm tag function of build API now imorts module

  import { esm } from "https://esm.sh/build";
  const mod = await esm`
    export const foo:string = "bar"
  `;
  console.log(mod.foo); // "bar"

• cjs-lexer: support annotated exports (close #659)

  // Annotate the CommonJS export names for ESM import in node:
  0 && (module.exports = {
    foo,
    bar
  });

  this is created by esbuild with cjs format, the cjs-lexer of esm.sh v125 or lower can't get the [foo,bar] export names.
• Add support for basic auth (#657 by @johnpangalos)