- v135_7Latest
- v135_6
- v136_6
- v135_5
- v135_4
- v135_3
- v135_2
- v135_1
- v135
- v134
- v133
- v132
- v131
- v130
- v129
- v128
- v127
- v126
- v125
- v124
- v123
- v122
- v121
- v120
- v119
- v118
- v117
- v116
- v115
- v114
- v113
- v112
- v111
- v110
- v109
- v108
- v107
- v106
- v105
- v104
- v103
- v102
- v101
- v100
- v99
- v98
- v97
- v96
- v95
- v94
- v93
- v92
- v91
- v90
- v89
- v88
- v87
- v86
- v85
- v84
- v83
- v82
- v81
- v80
- v79
- v78
- v77
- v76
- v75
- v74
- v73
- v72
- v71
- v70
- v69
- v68
- v67
- v66
- v65
- v64
- v63
- v62
- v61
- v60
- v59
- v56
- v57
- v55
- v53
- v52
- v51
- v50
- v49
- v48
- v47
- v46
- v45
- v44
- v43
- v41
- v40
- v39
- v38
- v37
- v35
- v34
- v0.1.0
- v0.0.1
esm.sh
A fast, smart, & global content delivery network (CDN) for modern(es2015+) web development.
Import from NPM
import React from "https://esm.sh/react@18.2.0"
You may also use a semver or a dist-tag instead of a fixed version number, or omit the version/tag entirely to use the latest
tag:
import React from "https://esm.sh/react" // 18.2.0 (latest)
import React from "https://esm.sh/react@17" // 17.0.2
import React from "https://esm.sh/react@canary" // 18.3.0-canary-7cd98ef2b-20230509
Submodule
import { renderToString } from "https://esm.sh/react-dom@18.2.0/server"
or import non-module(js) as following:
import "https://esm.sh/react@18.2.0/package.json" assert { type: "json" }
Import from GitHub Repo
You can also import modules/assets from a github repo: /gh/OWNER/REPO[@TAG]/PATH
. For example:
import tslib from "https://esm.sh/gh/microsoft/tslib"
or load a svg image from a github repo: https://esm.sh/gh/microsoft/fluentui-emoji/assets/Alien/Flat/alien_flat.svg
Specify Dependencies
By default, esm.sh rewrites import specifiers based on the package dependencies. To specify the version of these dependencies, you can add the ?deps=PACKAGE@VERSION
query. To specify multiple dependencies, separate them with a comma, like this: ?deps=react@17.0.2,react-dom@17.0.2
.
import React from "https://esm.sh/react@17.0.2"
import useSWR from "https://esm.sh/swr?deps=react@17.0.2"
Using Import Maps
Import Maps has been supported by most modern browsers and Deno natively. This allows bare import specifiers, such as import moment from "reat"
, to work.
esm.sh supports ?external=foo,bar
query to specify external dependencies. With this query, esm.sh will not rewrite the import specifiers of the specified dependencies. For example:
{
"imports": {
"preact": "https://esm.sh/preact@10.7.2",
"preact-render-to-string": "https://esm.sh/preact-render-to-string@5.2.0?external=preact",
}
}
Alternatively, you can mark all dependencies as external by adding a *
prefix before the package name:
{
"imports": {
"preact": "https://esm.sh/preact@10.7.2",
"preact-render-to-string": "https://esm.sh/*preact-render-to-string@5.2.0",
"swr": "https://esm.sh/*swr@1.3.0",
"react": "https://esm.sh/preact@10.7.2/compat",
}
}
Import maps supports trailing slash that can not work with URL search params friendly. To fix this issue, esm.sh provides a special format for import URL that allows you to use query params with trailing slash: change the query prefix ?
to &
and put it after the package version.
{
"imports": {
"react-dom": "https://esm.sh/react-dom@18.2.0?pin=v122&dev",
"react-dom/": "https://esm.sh/react-dom@18.2.0&pin=v122&dev/",
}
}
If you are using Deno, you can use the CLI Script to generate and update the import maps that will resolve the external dependencies automatically.
Aliasing Dependencies
import useSWR from "https://esm.sh/swr?alias=react:preact/compat"
in combination with ?deps
:
import useSWR from "https://esm.sh/swr?alias=react:preact/compat&deps=preact@10.5.14"
The origin idea was coming from @lucacasonato.
Tree Shaking
By default, esm.sh exports a module with all its exported members. However, if you want to import only a specific set of members, you can specify them by adding a ?exports=foo,bar
query to the import statement.
import { __await, __rest } from "https://esm.sh/tslib" // 7.3KB
import { __await, __rest } from "https://esm.sh/tslib?exports=__await,__rest" // 489B
By using this feature, you can take advantage of tree shaking with esbuild and achieve a smaller bundle size. Note that this feature is only supported for ESM modules and not CJS modules.
Bundle Mode
import { Button } from "https://esm.sh/antd?bundle"
In bundle mode, all dependencies are bundled into a single JS file except the peer dependencies.
Development Mode
import React from "https://esm.sh/react?dev"
With the ?dev
option, esm.sh builds a module with process.env.NODE_ENV
set to "development"
or based on the condition development
in the exports
field of package.json
. This is useful for libraries that have different behavior in development and production. For example, React will use a different warning message in development mode.
ESBuild Options
By default, esm.sh checks the User-Agent
header to determine the build target. You can also specify the target
by adding ?target
, available targets are: es2015 - es2022, esnext, deno, and denonext.
import React from "https://esm.sh/react?target=es2020"
Other supported options of esbuild:
- Conditions
import foo from "https://esm.sh/foo?conditions=custom1,custom2"
- Keep names
import foo from "https://esm.sh/foo?keep-names"
- Ignore annotations
import foo from "https://esm.sh/foo?ignore-annotations"
Web Worker
esm.sh supports ?worker
query to load the module as a web worker:
import workerFactory from "https://esm.sh/monaco-editor/esm/vs/editor/editor.worker?worker"
const worker = workerFactory()
You can pass some custom code snippet to the worker when calling the factory function:
const workerAddon = `
self.onmessage = function (e) {
console.log(e.data)
}
`
const worker = workerFactory(workerAddon)
Package CSS
<link rel="stylesheet" href="https://esm.sh/monaco-editor?css">
This only works when the package imports CSS files in JS directly.
Importing WASM Modules
esm.sh supports importing wasm modules in JS directly, to do that, you need to add ?module
query to the import URL:
import wasm from "https://esm.sh/@dqbd/tiktoken@1.0.3/tiktoken_bg.wasm?module"
const { exports } = WebAssembly.instantiate(wasm, imports)
Specify CJS Exports
If you get an error like ...not provide an export named...
, that means esm.sh can not resolve CJS exports of the module correctly. You can add ?cjs-exports=foo,bar
query to specify the export names:
import { NinetyRing, NinetyRingWithBg } from "https://esm.sh/react-svg-spinners@0.3.1?cjs-exports=NinetyRing,NinetyRingWithBg"
Building a Module with Custom Input(code)
This is an experimental API that allows you to build a module with custom input(code).
- Imports NPM/GH packages
- Supports TS/JSX syntaxes
- Bundle mulitple modules into a single JS file
import build, { esm } from "https://esm.sh/build"
// use `esm` tag function
const ret = await esm`
/* @jsx h */
import { h } from "preact@10.13.2";
import { renderToString } from "preact-render-to-string@6.0.2";
export function render(): string {
return renderToString(<h1>Hello world!</h1>);
}
`
// use `build` function
const ret = await build({
dependencies: {
"preact": "^10.13.2",
"preact-render-to-string": "^6.0.2"
},
code: `
/* @jsx h */
import { h } from "preact";
import { renderToString } from "preact-render-to-string";
export function render(): string {
return renderToString(<h1>Hello world!</h1>);
}
`,
// for types checking and LSP completion
types:`
export function render(): string;
`
})
// import module
const { render } = await import(ret.url)
// import bundled module
const { render } = await import(ret.bundleUrl)
render() // "<h1>Hello world!</h1>"
Deno Compatibility
esm.sh is a Deno-friendly CDN that resolves Nodeâs built-in modules (such as fs, os, etc.), making it compatible with Deno.
import express from "https://esm.sh/express";
const app = express();
app.get("/", (req, res) => {
res.send("Hello World");
});
app.listen(3000)
For users using deno < 1.31
, esm.sh uses deno.land/std@0.177.0/node as node compatibility layer. You can specify a different version by adding the ?deno-std=$VER
query:
import postcss from "https://esm.sh/postcss?deno-std=0.128.0"
X-Typescript-Types Header
Deno supports type definitions for modules with a types
field in their package.json
file through the X-TypeScript-Types
header. This makes it possible to have type checking and auto-completion when using those modules in Deno. (link).
In case the type definitions provided by the X-TypeScript-Types
header are incorrect, you can disable it by adding the ?no-dts
query to the module import URL:
import unescape from "https://esm.sh/lodash/unescape?no-dts"
This will prevent the X-TypeScript-Types
header from being included in the network request, and you can manually specify the types for the imported module.
Using CLI Script
esm.sh provides a CLI script for managing imports with import maps in Deno. This CLI script automatically resolves dependencies and uses a pinned build version for stability.
To use the esm.sh CLI script, you first need to run the init
command in your projectâs root directory:
deno run -A -r https://esm.sh init
Once youâve initialized the script, you can use the following commands to manage your imports:
# Adding packages
deno task esm:add react react-dom # add multiple packages
deno task esm:add react@17.0.2 # specify version
deno task esm:add react:preact/compat # using alias
# Updating packages
deno task esm:update react react-dom # update specific packages
deno task esm:update # update all packages
# Removing packages
deno task esm:remove react react-dom
Pinning Build Version
To ensure stable and consistent behavior, you may want to pin the build version of a module youâre using from esm.sh. This helps you avoid potential breaking changes in the module caused by updates to the esm.sh server.
The ?pin
query allows you to specify a specific build version of a module, which is an immutable cached version stored on the esm.sh CDN.
import React from "https://esm.sh/react-dom?pin=v122"
// or use version prefix
import React from "https://esm.sh/v122/react-dom"
By using the ?pin
query in the import statement, you can rest assured that the version of the module youâre using will not change, even if updates are pushed to the esm.sh server. This helps ensure the stability and reliability of your application.
For UI libraries like React and Vue, esm.sh uses a special build version stable
to ensure single version of the library is used in the whole application.
Global CDN
The Global CDN of esm.sh is provided by Cloudflare, one of the worldâs largest and fastest cloud network platforms.
Self-Hosting
To host esm.sh by yourself, check the hosting documentation.