UNPKG

UNPKG is a fast, global content delivery network for everything on npm. Use it to quickly and easily load any file on npm using a URL like:

unpkg.com/:pkg@:ver/:file

  • :pkg is the name of the package on npm
  • :ver is the version of the package
  • :file is the path to a file in the package

For example:

You can also use any valid semver range or npm tag:

If you don't specify a version, the latest tag is used by default.

Add a trailing / to a directory URL to view a listing of all the files in that directory.

If you'd like to browse an older version of a package, include a version number in the URL.

If you don't specify a file path, UNPKG will resolve the file based on the package's default entry point. In many packages that are meant solely for frontend development, like jQuery and GSAP, this will be the value of the main field in the package.json file.

In modern packages that use the exports field, UNPKG will resolve the file using the default export condition.

So, for example if you publish a package with the following package.json:

{ "name": "my-package", "exports": { "default": "./dist/index.js" } }

You would be able to load your package from UNPKG using a <script> tag like:

<script src="https://unpkg.com/my-package"></script>

The full exports spec is supported, including subpaths. So if your package.json looks like:

{ "name": "my-package", "exports": { "./exp": { "default": "./dist/exp.js" } } }

You can load the exp subpath with:

<script src="https://unpkg.com/my-package/exp"></script>

Custom export conditions are supported via the ?conditions query parameter. This allows you to load a different file based on the environment or other conditions. For example, to fetch React using the react-server condition, you could do:

fetch("https://unpkg.com/react?conditions=react-server")

If you'd like to specify a custom build of your package that should be used as the default entry point on UNPKG, you can use either the unpkg field in your package.json or the unpkg export condition in your exports field.

{ "name": "my-package", "unpkg": "./dist/index.unpkg.js", // This works "exports": { "unpkg": "./dist/index.unpkg.js" // This works, too "default": "./dist/index.js" } }

Nobuild Apps

UNPKG is ideal for loading dependencies in apps that run entirely in the browser without a build step. You can load JavaScript modules from UNPKG directly in your HTML using an import map.

Below is a fully functional Preact app that does not require a build in order to run.

<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <script type="importmap"> { "imports": { "preact": "https://unpkg.com/preact@10.25.4/dist/preact.module.js", "preact/hooks": "https://unpkg.com/preact@10.25.4/hooks/dist/hooks.module.js", "htm": "https://unpkg.com/htm@3.1.1/dist/htm.module.js" } } </script> </head> <body> <script type="module"> import { h, render } from "preact"; import { useState } from "preact/hooks"; import htm from "htm"; const html = htm.bind(h); function App() { let [count, setCount] = useState(0); return html` <div> <p>Count: ${count}</p> <button onClick=${() => setCount(count + 1)}>Increment</button> </div> `; } render(html`<${App} />`, document.body); </script> </body> </html>

No bundler required! This is ideal for small projects, prototypes, or any situation where you'd like to get something up and running quickly without setting up a build pipeline.

Metadata API

UNPKG serves metadata about the files in a package when you append ?meta to any package root or subdirectory URL.

For example:

This will return a JSON object with information about the files in that directory, including path, size, type, and subresource integrity value.

{ package: "react-router", version: "7.3.0", prefix: "/dist/", files: [ { path: "/dist/development/dom-export.js", size: 195045, type: "text/javascript", integrity: "sha256-z5j8OHOsGkvfGAjBtW8sbj+M68LLmgLTSjDHk4A5uYA=" }, { path: "/dist/production/dom-export.js", size: 195047, type: "text/javascript", integrity: "sha256-Gh8wMHW9MO5IMaBq7fOc7szDMRemnO/7Qr8kTK4ebgY=" }, // ... ] }

Cache Performance

UNPKG is a mirror of everything on npm. Every file on npm is automatically available on unpkg.com within minutes of being published.

Additionally, UNPKG runs on Cloudflare's global edge network using Cloudflare Workers, which allow UNPKG to serve billions of requests every day with low latency from hundreds of locations worldwide. The "serverless" nature of Cloudflare Workers also allows UNPKG to scale immediately to satisfy sudden spikes in traffic.

Files are cached on Cloudflare's global content-delivery network based on their permanent URL, which includes the npm package version. This works because npm does not allow package authors to overwrite a package that has already been published with a different one at the same version number.

URLs that do not specify a fully resolved package version number redirect to one that does. This is the latest version when none is specified, or the maximum satisfying version when a semver range is given. For the best chance of getting a cache hit, use the full package version number and file path in your UNPKG URLs instead of an npm tag or semver range.

For example, a URL like unpkg.com/preact@10 will not be a direct cache hit because UNPKG needs to resolve the version 10 to the latest matching version of Preact published with that major, plus it needs to figure out which file to serve. So a short URL like this will always cause a redirect to the permanent URL for that resource. If you need to make sure you hit the cache, use a fixed version number and the full file path, like unpkg.com/preact@10.5.0/dist/preact.min.js.

About

UNPKG is an open source project from @mjackson. UNPKG is not affiliated with or supported by npm in any way. Please do not contact npm for help with UNPKG. Instead, please reach out to @unpkg with any questions or concerns.