esm.sh: a no-build CDN that serves npm, JSR and GitHub packages as ES modules
A no-build JavaScript CDN for modern web development.
At a glance
- What is it?
- esm.sh rewrites import specifiers and transforms TypeScript, Vue and Svelte files on the fly, so a browser can import a package by URL. It is convenient for prototypes and demos, and a dependency you do not control for anything that ships to production.
- Who is it for?
- Adopt esm.sh for prototypes, documentation demos, import-map experiments and quick evaluations of a package before you commit to it, and for self-hosted deployments where you control the origin. Do not adopt it as the only delivery path for a production application whose availability matters, and do not use it to import code you have not reviewed.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- esm-dev/esm.sh4,196 ★ · +20
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| esm-dev/esm.sh | 4.2k | 4.2k |
20 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What problem esm.sh solves, and for whom
Browsers understand ES modules, but they do not understand bare specifiers. `import React from "react"` fails in a browser unless something resolves that name to a URL. The usual answer is a build step: a bundler reads `node_modules`, rewrites the specifiers, and emits a file the browser can load. That works, but it means a toolchain, a config file and a build before anything runs.
esm.sh removes the build step by doing the resolution on a server. You point an import at `https://esm.sh/PKG[@SEMVER][/PATH]` and get back JavaScript the browser can execute. The README describes the project as "a no-build JavaScript CDN for modern web development", and the supported registries are npm, JSR (URLs starting with `/jsr/`), GitHub (starting with `/gh/`) and pkg.pr.new (starting with `/pr/` or `/pkg.pr.new/`).
The audience is narrower than the tagline suggests. It fits people writing a single HTML file with a `<script type="module">` tag, people building import maps by hand, and people who want to try a package without installing it. It fits less well inside an application that already has a bundler, because then you have two resolution systems and only one of them is under your control.
How the CDN resolves, rewrites and bundles a package
The server is written in Go (`module github.com/esm-dev/esm.sh`, `go 1.26.0`) and depends on `github.com/ije/esbuild-internal` for transformation, `go.etcd.io/bbolt` for storage and `github.com/hashicorp/golang-lru/v2` for caching. The Dockerfile also copies a Deno binary into the image at `/esm/bin/deno`, which is how non-JavaScript sources such as `.vue` and `.svelte` files get compiled.
When a request arrives, the server fetches the package from the registry, reads its `package.json`, and rewrites the import specifiers inside the module according to the package's declared dependencies. The transformed module is cached and served. Because the rewrite happens per request, the same package can be served with different dependency versions depending on the query string.
The default bundling rule is the part worth understanding. The README states that esm.sh bundles sub-modules of a package that are not shared by entry modules defined in the `exports` field of `package.json`. Bundling reduces the number of network requests. It can also duplicate shared modules, and the README is explicit that in extreme cases this can break package side effects or change `import.meta.url` semantics. The escape hatch is `?bundle=false`. The project's own recommendation is that package authors define `exports` so the dependency tree can be analysed without duplication, or set the `esm.sh` field in `package.json` with `"bundle": false`.
Installing esm.sh: the hosted URL and a self-hosted server
There is nothing to install to use the hosted service. The README's first example is a single import from an https URL, and the browser does the rest:
import * as mod from "https://esm.sh/PKG[@SEMVER][/PATH]";For bare specifiers, the README gives an import map that maps `react` and the `react-dom/` prefix to versioned URLs, so the rest of the page can use normal imports:
<script type="importmap">
{
"imports": {
"react": "https://esm.sh/[email protected]",
"react-dom/": "https://esm.sh/[email protected]/"
}
}
</script>
<script type="module">
import React from "react";
import { render } from "react-dom/client";
</script>To run your own instance, the repository ships a Dockerfile and a `HOSTING.md`. The Dockerfile builds `server/esmd/main.go` with `CGO_ENABLED=0`, stamps the version from the `SERVER_VERSION` build argument, copies the Deno binary into `/esm/bin/deno`, sets `ESMDIR="/esm"` and exposes port 80. The container runs as the unprivileged `esm` user. The `Makefile` shows the local development path, which reads a `config.json` and wipes `.esmd/log` and `.esmd/storage` before starting the server:
make run/serverThe repository also includes `config.example.jsonc` as the starting point for that config file. The README does not document the individual config keys, so treat the example file as the source of truth for what the server accepts. For the command line side, the `Makefile` exposes `make run/cli/add` and `make run/cli/tidy`, which run `main.go add` and `main.go tidy` under the `debug` build tag.
Pinning dependency versions with the deps and alias queries
The interesting design decision in esm.sh is that dependency resolution is a query parameter rather than a lockfile. By default the server rewrites specifiers based on the package's own declared dependencies. To force a version, you append `?deps=PACKAGE@VERSION`, and multiple dependencies are comma separated:
import React from "https://esm.sh/[email protected]";
import useSWR from "https://esm.sh/[email protected]";There is also `?alias=PACKAGE:ALIAS`, which the README shows being combined with `?deps` to swap React for Preact's compatibility layer. Two more queries matter in practice. `?exports=foo,bar` limits the exported members, which the README illustrates with a tslib import dropping from 7.3KB to 489B, though it notes the feature does not work with CommonJS modules. `?dev` builds with `process.env.NODE_ENV` set to `"development"` or the `development` export condition, which is what you want when a library prints different warnings in each mode.
The consequence is that the URL is the manifest. Every dependency decision lives in the import statement, which is readable but also means there is no single file to audit. A page with twelve imports has twelve independent resolution decisions, and nothing warns you when one of them changes.
Transforming TypeScript, Vue and Svelte files without a build
The feature that distinguishes esm.sh from a plain file CDN is that it will compile sources it fetches. The README shows a `.tsx` file and a `.vue` file imported directly from GitHub, with `?deps` used to pin the framework version the component compiles against:
import { Airplay } from "https://esm.sh/gh/phosphor-icons/[email protected]/src/csr/[email protected]";
import IconAirplay from "https://esm.sh/gh/phosphor-icons/[email protected]/src/icons/[email protected]";This is why the Docker image carries Deno. Compiling Vue and Svelte single-file components is not something esbuild does on its own, and the server needs the extra runtime to handle those formats. It also explains why the image is larger than a plain Go binary would be, and why the Dockerfile contains a workaround to make Deno's glibc build run on Alpine, which does not have a musl build from Deno yet.
If you want the source untouched, `?raw` disables the default transforming and bundling behaviour. The README's tip describes it as importing the raw JavaScript source as-is, without transformation into ES modules. That is the flag to reach for when the transform is the thing breaking your import.
Where esm.sh is the wrong tool
The largest limitation is architectural: your application's module graph depends on a service you do not run. If esm.sh is unreachable, the imports fail and the page does not load. The README documents no fallback, no retry strategy and no offline mode, and the repository has no documented SLA. That is acceptable for a demo and not acceptable for a checkout page.
The second limitation is version drift. A URL like `https://esm.sh/react` resolves to the latest version, and the README's own examples use bare package names for the latest release. Any import written that way can change under you without a commit. Pinning with `@SEMVER` fixes that, but nothing in the tooling enforces pinning, so it is a convention rather than a guarantee.
The third is supply chain. Every import executes code published by a third party, fetched and transformed by a third party, at page load. The README does not describe a review process, a signature check or an allowlist. The `?exports` query is a size optimisation, not a security boundary, and the README notes it does not work with CommonJS modules anyway. If your threat model includes the packages you load, esm.sh does not change it; it just moves the fetch to runtime.
Finally, the bundling default can surprise you. The README warns that bundling shared sub-modules can break side effects or `import.meta.url`, which is exactly the class of bug that is hard to reproduce locally and easy to hit in a package that was never designed for a CDN.
esm.sh compared with unpkg and jsDelivr
unpkg and jsDelivr both serve npm package files over HTTP, and both will hand you a file from a package. The difference is what arrives. unpkg and jsDelivr serve the file as published, so a CommonJS module stays CommonJS and a bare specifier inside it stays bare. esm.sh rewrites specifiers and converts packages to ES modules, which is why an import from esm.sh usually works in a browser without further work and an import from a plain file CDN often does not.
That extra step is also the cost. A file CDN is a dumb pipe: the bytes you get are the bytes that were published, and caching is straightforward. esm.sh runs a build per request and caches the result, so the response depends on the server's version, its bundling heuristics and its dependency resolution. When something breaks, the question is whether the package changed or the CDN's transform changed, and the answer is not in your repository.
If you need the transform, the honest comparison is not esm.sh against another CDN but esm.sh against running the same transform yourself. The repository is MIT licensed and ships a Dockerfile, so self-hosting is the option that keeps the convenience and removes the third-party runtime dependency. For a project that only needs to serve already-built ES modules, a plain file CDN is simpler and has fewer moving parts.
Maintenance, licence and the cost of upgrading
The repository is not archived, and the last push was on 2026-09-21. The recent releases are `v139` on 2026-09-14, `v139_1` on 2026-09-17 and `v139_2` on 2026-09-21, which indicates a release cadence measured in days rather than months. The root of the repository contains `CHANGELOG-SERVER.md` and `CHANGELOG-CLI.md`, so the release history is written down in two places rather than one.
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. Nothing in the repository suggests a copyleft obligation or a separate commercial licence. This is a description of the licence text, not legal advice; if you are redistributing a modified server, read the LICENSE file and get your own answer.
The upgrade cost is asymmetric between the two ways of using the project. If you only consume the hosted URLs, upgrading is not an action you take: the server moves and your imports follow. That is the same property that makes version drift a risk. If you self-host, upgrading means rebuilding the image, and the `SERVER_VERSION` build argument is what stamps the version into the binary. The Dockerfile pins the Deno base image to `denoland/deno:bin-2.7.13`, so a Deno upgrade is a deliberate edit rather than something that arrives on its own. The repository layout suggests the test path is `make test/server`, which runs `./test/bootstrap.ts` with a directory argument.
Editorial conclusion
Adopt esm.sh for prototypes, documentation demos, import-map experiments and quick evaluations of a package before you commit to it, and for self-hosted deployments where you control the origin. Do not adopt it as the only delivery path for a production application whose availability matters, and do not use it to import code you have not reviewed. Before committing, verify three things: whether the packages you need resolve to the versions you expect, whether the bundling default is acceptable for them, and whether the public instance is reachable from your users' networks. The Dockerfile in the repository builds the server with the version stamped from the SERVER_VERSION build argument, so a self-hosted instance is a build you own rather than a service you depend on.
Frequently asked questions
What is esm.sh?
It is a no-build JavaScript CDN. You import a package from an https URL such as `https://esm.sh/PKG[@SEMVER][/PATH]` and the server resolves it from npm, JSR, GitHub or pkg.pr.new, rewrites the import specifiers and returns an ES module the browser can run.
What does https://esm.sh actually serve?
It serves transformed JavaScript modules. According to the README, the server fetches the package, rewrites specifiers based on the package's dependencies, and by default bundles sub-modules that are not shared by entry modules declared in the `exports` field of `package.json`.
Is esm.sh safe to use?
The README does not document a review process, signature check or allowlist for the packages it serves, and every import executes third-party code fetched at page load. The `?exports` query reduces the exported members but the README notes it does not work with CommonJS modules, so it is a size optimisation rather than a security control.
How is esm.sh different from unpkg or jsDelivr?
The file CDNs serve a package's files as published, so a CommonJS module stays CommonJS and bare specifiers stay bare. esm.sh rewrites specifiers and converts packages to ES modules, which is why its URLs usually work directly in a browser without a build step.
How do I pin a dependency version in an esm.sh import?
Append `?deps=PACKAGE@VERSION` to the import URL, and separate multiple dependencies with commas, as in `[email protected],[email protected]`. The README also documents `?alias=PACKAGE:ALIAS` for substituting one package for another.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/esm-dev-esm-sh)Star history chart for your README
[](https://hysenlabs.com/projects/esm-dev-esm-sh)Was this useful?