Skip to main content

ESM

A fast, global content delivery network to transform NPM packages to standard ES Modules by esbuild.

Import from URL

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

Specify version

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

or import a major version:

import React from 'https://esm.sh/react@17'

Submodule

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

or import non-module(js) files:

import 'https://esm.sh/tailwindcss/dist/tailwind.min.css'

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 mode builds code with process.env.NODE_ENV equals to development, that is useful to build modules like React to allow you get more development warn/error details.

Specify external 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.

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 came from @lucacasonato.

Specify ESM target

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

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 - es2021, esnext, node, and deno.

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.

Web Worker

esm.sh supports ?worker mode to load modules as web worker:

import editorWorker from '/monaco-editor/esm/vs/editor/editor.worker?worker'
  
const worker = new editorWorker()

Deno compatibility

esm.sh will resolve the node internal modules (fs, child_process, etc.) with deno.land/std/node to support some packages working in Deno, like postcss:

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()

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-check query to disable the X-TypeScript-Types header if some types are incorrect:

import unescape from 'https://esm.sh/lodash/unescape?no-check'

Pin the build version

Since we update esm.sh server very frequently, sometime we may break some packages that work fine previously by mistake, because we need to rebuild all modules when the patch pushed. To avoid this, you can pin the build version by the ?pin=BUILD_VERSON query. 

import React from 'https://esm.sh/react@17.0.2?pin=v57'

Network of esm.sh

Self-Hosting

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