Skip to main content

ESM

A fast, global content delivery network for NPM packages with ES Module format.

Import from URL

import React from "https://esm.sh/react"

Specify version

import React from "https://esm.sh/react@17.0.2"

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@17"   // 17.0.2
import React from "https://esm.sh/react@next" // 18.0.0-rc.0-next-13036bfbc-20220121

Submodule

import { renderToString } from "https://esm.sh/react-dom/server"

or import non-module(js) files:

import "https://esm.sh/react/package.json" assert { type: "json" }

Specify dependencies

import React from "https://esm.sh/react@16.14.0"
import useSWR from "https://esm.sh/swr?deps=react@16.14.0"

By default, esm.sh rewrites import specifier based on the package’s dependency statement. To specify version of dependencies, you can use the ?deps=PACKAGE@VERSION query. You can separate multiple dependencies with commas: ?deps=react@16.14.0,react-dom@16.14.0.

Specify external dependencies

{
  "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",
  }
}

You can use the ?external=PACKAGE query to specify external dependencies. Or you can mark all dependencies as external by add * 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",
  }
}

These dependencies will not be resolved with the code. You need to use import maps to specify the location for these dependencies.

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.

Bundle mode

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

In bundle mode, all dependencies will be bundled into a single JS file.

Development mode

import React from "https://esm.sh/react?dev"

The ?dev query builds modules with process.env.NODE_ENV equals to development, that is useful to build modules like React to allow you to get more development warn/error details.

ESBuild options

By default, esm.sh will check the User-Agent header to get the build target automatically. You can specify it with the ?target query. Available targets: es2015 - es2022, esnext, node, and deno.

import React from "https://esm.sh/react?target=es2020"

Other supported options of esbuild:

  • Keep names

    import React from "https://esm.sh/react?keep-names"

  • Ignore annotations

    import React from "https://esm.sh/react?ignore-annotations"

  • Sourcemap

    import React from "https://esm.sh/react?sourcemap"

    This only supports the inline mode.

Package CSS

import Daygrid from "https://esm.sh/@fullcalendar/daygrid"
<link rel="stylesheet" href="https://esm.sh/@fullcalendar/daygrid?css">

This only works when the NPM module imports CSS files in JS directly.

Deno compatibility

esm.sh will resolve the node internal modules (fs, child_process, etc.) with deno.land/std/node to support Deno.

import postcss from "https://esm.sh/postcss"
import autoprefixer from "https://esm.sh/autoprefixer"

const { css } = await postcss([ autoprefixer ]).process(`
  backdrop-filter: blur(5px);
  user-select: none;
`).async()

By default esm.sh will use a fixed version of deno.land/std/node. You can use the ?deno-std=$VER query to specify a different version:

import postcss from "https://esm.sh/postcss?deno-std=0.128.0"

Use CLI Script

The CLI script is using to manage the imports with import maps, it will resolve the dependencies automatically and always pin the build version. To use the CLI mode, you need to run the init command in your project root directory:

deno run -A -r https://esm.sh init

After initializing, you can use the deno task npm:[add/update/remove] commands to manage the npm modules in the import maps.

deno task npm:add react react-dom # add packages
deno task npm:add react@17 # add packages with specified version
deno task npm:add react:preact/compat # add packages with alias
deno task npm:update react react-dom # upgrade packages
deno task npm:update # update all packages
deno task npm:remove react react-dom # remove packages

X-Typescript-Types

By default, esm.sh will respond with a custom X-TypeScript-Types HTTP header when the types (.d.ts) is defined. This is useful for deno type checks (link).

Figure #1

You can pass the ?no-dts query to disable the X-TypeScript-Types header if some types are incorrect:

import unescape from "https://esm.sh/lodash/unescape?no-dts"

Pin the build version

Since we update esm.sh server frequently, sometime we may break packages that work fine previously by mistake, the server will rebuild all modules when the patch pushed. To avoid this, you can pin the build version by the ?pin=BUILD_VERSON query. This will give you an immutable cached module.

import React from "https://esm.sh/react@17.0.2?pin=v95"

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.