Repository files navigation

Ano-build JavaScript CDN for modern web development.

esm.sh allows you to importJavaScript modules from http URLs,no installation/build steps needed.

import*asmodfrom"https://esm.sh/PKG[@SEMVER][/PATH]";

Withimport maps, you can even use bare import specifiers instead of URLs:

<scripttype="importmap">{"imports":{"react":"https://esm.sh/react@19.2.0","react-dom/":"https://esm.sh/react-dom@19.2.0/"}}</script><scripttype="module">importReactfrom"react";// → https://esm.sh/react@19.2.0import{render}from"react-dom/client";// → https://esm.sh/react-dom@19.2.0/client</script>

More usages about import maps can be found in theUsing Import Maps section.

• NPM:

  // ExamplesimportReactfrom"https://esm.sh/react";// latestimportReactfrom"https://esm.sh/react@18";// 18.3.1importReactfrom"https://esm.sh/react@beta";// latest betaimport{renderToString}from"https://esm.sh/react-dom/server";// sub-modules

• JSR (starts with/jsr/):

  // Examplesimport{encodeBase64}from"https://esm.sh/jsr/@std/encoding@1.0.0/base64";import{Hono}from"https://esm.sh/jsr/@hono/hono@4";

• GitHub (starts with/gh/):

  // Examplesimporttslibfrom"https://esm.sh/gh/microsoft/tslib";// latestimporttslibfrom"https://esm.sh/gh/microsoft/tslib@d72d6f7";// with commit hashimporttslibfrom"https://esm.sh/gh/microsoft/tslib@v2.8.0";// with tag

• pkg.pr.new (starts with/pr/ or/pkg.pr.new/):

  // Examplesimport{Bench}from"https://esm.sh/pr/tinylibs/tinybench/tinybench@a832a55";import{Bench}from"https://esm.sh/pr/tinybench@a832a55";// --compact

esm.sh allows you to import.ts(x),.vue, and.svelte files directly in the browser without any build steps.

import{Airplay}from"https://esm.sh/gh/phosphor-icons/react@v2.1.5/src/csr/Airplay.tsx?deps=react@19.2.0";importIconAirplayfrom"https://esm.sh/gh/phosphor-icons/vue@v2.2.0/src/icons/PhAirplay.vue?deps=vue@3.5.8";

By default, esm.sh rewrites import specifiers based on the package dependencies. To specify the version of thesedependencies, you can add?deps=PACKAGE@VERSION to the import URL. To specify multiple dependencies, separate them with commas, like this:?deps=react@18.3.1,react-dom@18.3.1.

importReactfrom"https://esm.sh/react@18.3.1";importuseSWRfrom"https://esm.sh/swr?deps=react@18.3.1";

You can also alias dependencies by adding?alias=PACKAGE:ALIAS to the import URL. This is useful when you want to use a different package for a dependency.

importuseSWRfrom"https://esm.sh/swr?alias=react:preact/compat";

in combination with?deps:

importuseSWRfrom"https://esm.sh/swr?alias=react:preact/compat&deps=preact@10.5.14";

By default, esm.sh bundles sub-modules of a package that are not shared by entry modules defined in theexports field ofpackage.json.

Bundling sub-modules can reduce the number of network requests, improving performance. However, it may result in repeated bundling of shared modules. In extreme cases, this can break package side effects or alter theimport.meta.url semantics. To prevent this, you can disable the default bundling behavior by adding?bundle=false:

import"https://esm.sh/@pyscript/core?bundle=false";

For package authors, it is recommended to define theexports field inpackage.json. This specifies the entry modules of the package, allowing esm.sh to accurately analyze the dependency tree and bundle the modules without duplication.

{"name":"foo","exports": {".": {"import":"./index.js","require":"./index.cjs","types":"./index.d.ts"    },"./submodule": {"import":"./submodule.js","require":"./submodule.cjs","types":"./submodule.d.ts"    }  }}

Or you can override the bundling strategy by adding theesm.sh field to yourpackage.json:

{"name":"foo","esm.sh": {"bundle":false// disables the default bundling behavior  }}

You can also add the?standalone flag to bundle the module along with all its external dependencies (excluding those inpeerDependencies) into a single JavaScript file.

import{Button}from"https://esm.sh/antd?standalone";

You can disable the default transforming/bundling behavior by adding?raw query to the import URL.

import{render}from"https://esm.sh/preact?raw";

By default, esm.sh exports a module with all its exported members. However, if you want to import only a specific set ofmembers, you can specify them by adding a?exports=foo,bar query to the import statement.

import{__await,__rest}from"https://esm.sh/tslib";// 7.3KBimport{__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,this feature doesn't work with CommonJS modules.

importReactfrom"https://esm.sh/react?dev";

With the?dev query, esm.sh builds a module withprocess.env.NODE_ENV set to"development" or based on theconditiondevelopment in theexports field. This is useful for libraries that have different behavior in developmentand production. For example, React uses a different warning message in development mode.

By default, esm.sh checks theUser-Agent header to determine the build target. You can also specify thetarget byadding?target, available targets are:es2015 -es2024,esnext,deno,denonext, andnode.

importReactfrom"https://esm.sh/react?target=es2022";

Other supported options of esbuild:

• Conditions

  importfoofrom"https://esm.sh/foo?conditions=custom1,custom2";

• Keep names

  importfoofrom"https://esm.sh/foo?keep-names";

• Ignore annotations

  importfoofrom"https://esm.sh/foo?ignore-annotations";

esm.sh supports importing CSS files in JS directly:

<linkrel="stylesheet"href="https://esm.sh/monaco-editor?css">

esm.sh supports?worker query to load the module as a web worker:

importcreateWorkerfrom"https://esm.sh/monaco-editor/esm/vs/editor/editor.worker?worker";// create a workerconstworker=createWorker();// rename the worker by adding the `name` option for debuggingconstworker=createWorker({name:"editor.worker"});// inject code into the workerconstworker=createWorker({inject:"self.onmessage = (e) => self.postMessage(e.data)"});

You can import any module as a worker from esm.sh with the?worker query. Plus, you can access the module's exports in theinject code. For example, use thexxhash-wasm to hash strings in a worker:

importcreateWorkerfrom"https://esm.sh/xxhash-wasm@1.0.2?worker";// variable '$module' is the imported 'xxhash-wasm' moduleconstinject=`const { default: xxhash } = $moduleself.onmessage = async (e) => {  const hasher = await xxhash()  self.postMessage(hasher.h64ToString(e.data))}`;constworker=createWorker({ inject});worker.onmessage=(e)=>console.log("hash is",e.data);worker.postMessage("The string that is being hashed");

Import Maps has been supported by most modern browsers and Deno natively.This allowsbare import specifiers, such asimport React from "react", to work.

esm.sh introduces the?external for specifying external dependencies. By employing this query, esm.sh maintains the import specifier intact, leaving it to the browser/Deno to resolve based on the import map. For example:

<scripttype="importmap">{"imports":{"preact":"https://esm.sh/preact@10.7.2","preact/":"https://esm.sh/preact@10.7.2/","preact-render-to-string":"https://esm.sh/preact-render-to-string@5.2.0?external=preact"}}</script><scripttype="module">import{h}from"preact";import{useState}from"preact/hooks";import{render}from"preact-render-to-string";</script>

Alternatively, you canmark 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 supportstrailing slash that cannot work with URL search params friendly. To fix this issue, esm.sh provides a special format for import URL that allowsyou 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@19.2.0?dev","react-dom/":"https://esm.sh/react-dom@19.2.0&dev/"  }}

By default, esm.sh transforms (and bundles if necessary) the JavaScript source code. However, 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.

Theraw mode works just like other CDN services, unpkg.com(https://unpkg.com/), jsdelivr.net(https://www.jsdelivr.net/), etc.

<scriptsrc="https://esm.sh/p5/lib/p5.min.js?raw"></script>

esm.sh is aDeno-friendly CDN that resolves Node's built-in modules (such asfs,os,net, etc.), makingit compatible with Deno.

importexpressfrom"https://esm.sh/express";constapp=express();app.get("/",(req,res)=>{res.send("Hello World");});app.listen(3000);

Deno supports type definitions for modules with atypes field in theirpackage.json file through theX-TypeScript-Types header. This makes it possible to have type checking and auto-completion when using those modulesin Deno. (link).

In case the type definitions provided by theX-TypeScript-Types header is incorrect, you can disable it by adding the?no-dts query to the module import URL:

importunescapefrom"https://esm.sh/lodash/unescape?no-dts";

This will prevent theX-TypeScript-Types header from being included in the network request, and you can manuallyspecify the types for the imported module.

esm.sh is not supported by Node.js/Bun currently.

The Global CDN of esm.sh is provided byCloudflare, one of the world's largest and fastestcloud network platforms.

To host esm.sh by yourself, check thehosting documentation.

Under theMIT license.