Skip to main content
Module

x/esm/HOSTING.md

A fast, smart, & global CDN for modern(es2015+) web development.
esm-dev/esm.sh
Latest
File

Self-Hosting

esm.sh provides a fast, global CDN(content delivery network) publicly which is powered by Cloudflare. You can also host esm.sh server by yourself.

To serve esm.sh, You will need Go 1.18+ to compile the server. The server will install Node.js runtime automatically if it’s not found on your host machine.

  • Linux system with git installed
  • 4x CPU cores or more
  • 8GB RAM or more
  • 100GB disk space or more

Clone code

git clone https://github.com/esm-dev/esm.sh
cd esm.sh

Configration

To configure the server, create a config.json file then pass it to the server bootstrap command. For example:

// config.json
{
  "port": 8080,
  "workDir": "/var/www/esmd",
  "storage": "local:/var/www/esmd/storage",
  "origin": "https://esm.sh",
  "npmRegistry": "https://registry.npmjs.org/",
  "npmToken": "xxxxxx"
}

You can find all the server options in config.exmaple.jsonc. (Note: the config.example.jsonc is not a valid JSON file, it’s a JSONC file.)

Run the Sever Locally

go run main.go --config=config.json --dev

Then you can import React from http://localhost:8080/react

Deploy with Docker

esm.sh provides a docker image for deployment. You can pull the container image from https://ghcr.io/esm-dev/esm.sh.

docker pull ghcr.io/esm-dev/esm.sh      # latest version
docker pull ghcr.io/esm-dev/esm.sh:v135 # specific version

Run the container:

docker run -p 8080:8080 \
  -e NPM_REGISTRY=https://registry.npmjs.org/ \
  -e NPM_TOKEN=xxxxxx \
  ghcr.io/esm-dev/esm.sh:latest

Available environment variables:

  • CDN_ORIGIN: The origin of CDN, default is using the origin of the request.
  • CDN_BASE_PATH: The base path of CDN, default is “/”.
  • NPM_REGISTRY: The NPM registry, default is “https://registry.npmjs.org/”.
  • NPM_TOKEN: The NPM token for private packages.
  • NPM_REGISTRY_SCOPE: The NPM registry scope, default is no scope.
  • NPM_USER: The NPM user for private packages.
  • NPM_PASSWORD: The NPM password for private packages.
  • SERVER_AUTH_SECRET: The server auth secret, default is no auth.

You can also create your own Dockerfile with ghcr.io/esm-dev/esm.sh:

FROM ghcr.io/esm-dev/esm.sh
ADD ./config.json /etc/esmd/config.json
CMD ["esmd", "--config", "/etc/esmd/config.json"]

Deploy to Single Machine with the Quick Deploy Script

Ensure the supervisor has been installed on your host machine.

./scripts/deploy.sh --init

Deploy with Cloudflare Workers

We use Cloudflare Workers as the front layer to handle and cache esm.sh requests at edge(earth). We open sourced the code, you can use it to build your own esm.sh CDN running globally.

More details check esm-worker.