UNPKG Explained

UNPKG is a fast, global content delivery network for everything on npm. It allows developers to load files from published npm packages directly in a browser using a simple URL. Instead of downloading a package to a project and serving its files from your own server, you can reference a public UNPKG URL for the resource you need.

UNPKG is particularly useful for JavaScript libraries, CSS files, browser demos, documentation, prototypes and other projects that need direct access to files published through npm. Its URL structure makes it possible to select a package, version and individual file.

What Is UNPKG?

UNPKG is an npm-based CDN. It serves files that are available in npm packages through HTTP URLs that can be requested by browsers, applications and other clients.

The service does not replace npm as a package manager. npm is used to publish and manage packages, while UNPKG provides a way to deliver the published package contents over a CDN.

npm package
 ↓
UNPKG
 ↓
CDN
 ↓
Browser or other HTTP client

How UNPKG Works

When a client requests a UNPKG URL, the URL identifies an npm package and optionally its version and file. UNPKG resolves the requested package resource and serves it through its CDN infrastructure.

Browser
   ↓
UNPKG URL
   ↓
CDN infrastructure
   ↓
Resolve npm package
   ↓
Find requested file
   ↓
Return resource

Because the content is delivered through a CDN, users can access package files without the website developer maintaining a separate server for those assets. Frequently requested resources can also benefit from CDN caching and distributed delivery.

Basic UNPKG URL Structure

A basic UNPKG URL contains the package name after the domain. A version and file path can then be added when more precise control is required.

https://unpkg.com/package@version/file

Loading a Package File

Suppose an npm package contains a browser-ready JavaScript file. You can reference that file directly from HTML using its UNPKG URL.

<script src="https://unpkg.com/example-package@1.2.3/dist/example.min.js"></script>

The browser treats the URL like any other external resource. It sends an HTTP request, receives the JavaScript file and then processes it according to the HTML element used to reference it.

Using a Specific Version

UNPKG URLs can include an exact package version. This is one of the most important features for production use because it allows a website to reference a known package release instead of depending on whichever version happens to be current.

https://unpkg.com/example-package@1.2.3/dist/example.min.js

The @1.2.3 portion identifies the package version. If a later version of the package is published, the URL still refers to version 1.2.3.

Using an Unversioned URL

A UNPKG URL can omit the version and reference the package directly.

https://unpkg.com/example-package/dist/example.min.js

An unversioned package URL can resolve to the package version selected according to the package's published metadata. This is convenient for quick examples, but it does not provide the same level of dependency stability as an exact version.

Selecting a File

An npm package can contain many files. UNPKG allows you to specify the path to a particular file when you know which asset the application needs.

https://unpkg.com/package@1.2.3/dist/index.min.js

The exact path depends on the package. Some packages use dist, lib or browser directories, while others place their main files at the package root.

Package Metadata and package.json

npm packages normally contain a package.json file that describes the package, including its name, version and other metadata. UNPKG can expose files from the package, including package metadata, through its URL structure.

https://unpkg.com/example-package@1.2.3/package.json

This can be useful when inspecting how a package is structured or determining which files and metadata are included in a published package.

What Happens When You Request a Package Root?

When a URL does not specify a particular file, UNPKG can use package metadata to determine the appropriate entry point for the requested package. This behavior makes simple package URLs convenient for examples and browser usage.

The exact resource selected depends on the package metadata and the way the package is published. For production dependencies, explicitly referencing the intended file can provide clearer control when the package exposes multiple browser-related assets.

UNPKG and package.json Fields

Package metadata can contain fields that help tools determine which files or entry points should be used. Modern packages may provide different entry points for different environments, such as browser and server environments.

This is one reason developers should not assume that every npm package can simply be inserted into a browser with a script tag. A package may be designed primarily for a bundler or a Node.js environment rather than direct browser execution.

UNPKG and JavaScript Modules

Modern JavaScript packages may provide ES modules that can be loaded using a module script. When a package exposes a browser-compatible module file, it can be referenced from HTML using type="module".

<script type="module">
  import example from "https://unpkg.com/example-package@1.2.3/dist/index.js";

  console.log(example);
</script>

Whether a package can be used this way depends on how the package is built and what it exports. A CDN can deliver a file, but it does not automatically convert every package into browser-compatible code.

UNPKG and CSS

UNPKG can also serve CSS files contained in npm packages. If a package publishes a stylesheet, it can be referenced from HTML with a link element.

<link
  rel="stylesheet"
  href="https://unpkg.com/example-package@1.2.3/dist/example.min.css"
/>

This approach is useful for browser-based examples, documentation and simple static websites that want to use a published CSS package without adding a local build step.

UNPKG and Other Static Files

An npm package is not limited to JavaScript. Packages can contain many types of public files, and UNPKG can serve files that exist in the published package.

• JavaScript files.
• CSS files.
• JSON data.
• Source maps.
• Images.
• Fonts.
• Documentation assets.
• Other static package files.

UNPKG and CDN Caching

UNPKG uses CDN infrastructure to distribute npm package content. Caching allows frequently requested resources to be delivered efficiently without requiring every browser request to retrieve the original package content again.

First request
Browser → UNPKG → package source
                     ↓
                   file
                     ↓
                    CDN

Later request
Browser → CDN cache → file

Caching is particularly valuable for popular open-source packages because the same immutable package versions can be requested by many websites and users.

Why Versioned Packages Work Well With CDN Caching

Published package versions provide stable identifiers for npm content. When a URL contains a specific version, the resource can be treated as a distinct versioned asset instead of a moving reference.

https://unpkg.com/library@1.0.0/file.js
https://unpkg.com/library@1.1.0/file.js
https://unpkg.com/library@2.0.0/file.js

Each URL identifies a different package version. This is useful for caching and makes dependency upgrades an explicit change to the URL.

UNPKG and npm Versions

npm packages use semantic versioning frequently, so a package may have releases such as 1.4.0, 1.4.1 and 2.0.0. UNPKG URLs can use those exact versions to select the required package release.

For production applications, exact versions are usually the safest choice when a CDN URL is used as a direct dependency reference.

UNPKG and Semantic Version Ranges

Package managers such as npm can work with semantic version ranges such as ^1.2.0 or ~1.2.0. A CDN URL is different because it identifies an HTTP resource. When reproducibility matters, using an exact package version in the URL avoids ambiguity about which release is being loaded.

UNPKG in a Simple HTML Project

One advantage of UNPKG is that it can be used without npm installation or a JavaScript build system. A simple HTML document can reference a browser-compatible package directly.

<!DOCTYPE html>
<html>
  <head>
    <title>UNPKG Example</title>
  </head>
  <body>
    <script src="https://unpkg.com/example-package@1.2.3/dist/example.min.js"></script>
  </body>
</html>

This can be useful for quick prototypes, educational examples and small static websites where installing and bundling a package would add unnecessary setup.

UNPKG vs npm Installation

Using a CDN and installing a package locally are two different dependency strategies. A local installation gives the project direct control over the package through its package manager and build process. A CDN lets the browser fetch the resource directly from an external service.

UNPKG vs jsDelivr

UNPKG and jsDelivr are both popular ways to deliver npm package files through a CDN. They have similar basic use cases but use different infrastructure and URL formats.

Neither service is universally better for every project. The choice can depend on the project's CDN requirements, preferred URL format, source repositories and deployment strategy.

UNPKG vs Self-Hosting

Self-hosting a dependency means the website serves the asset from its own infrastructure or storage. Using UNPKG delegates delivery of that resource to an external CDN.

When Should You Use UNPKG?

UNPKG is particularly useful when a project needs quick access to a public npm package without setting up a local package installation or asset hosting system.

• Static HTML websites.
• Code examples and documentation.
• Small prototypes.
• Educational projects.
• Quick browser experiments.
• Public JavaScript libraries.
• Simple CSS dependencies.

When Should You Prefer a Package Manager?

For larger applications, package managers usually provide better dependency control. npm, pnpm and Yarn can install packages locally, resolve dependency trees and integrate them with modern build systems.

A package manager is generally preferable when the application needs bundling, tree shaking, automated dependency updates, local development, testing and reproducible builds.

UNPKG and Production Applications

UNPKG can be used in production, but the decision should be deliberate. A production application that directly depends on an external CDN introduces an additional service into the runtime delivery path.

Before using a CDN dependency in production, consider availability, versioning, security, performance, browser caching and what happens if the external resource cannot be reached.

Security Considerations

Loading JavaScript from an external CDN means that your application is trusting the content delivered by that service. Dependency versioning and integrity protection can reduce some risks, but they do not replace general dependency security practices.

Subresource Integrity

Subresource Integrity, commonly called SRI, allows a browser to verify that a fetched external resource matches an expected cryptographic hash. It can be useful when loading third-party JavaScript or CSS resources whose exact contents are known.

<script
  src="https://unpkg.com/example-package@1.2.3/dist/example.min.js"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>

If the resource content changes and no longer matches the expected hash, the browser can reject it. SRI therefore works particularly well with fixed, versioned resources.

Performance Considerations

A CDN can improve asset delivery, but adding an external dependency is not automatically a performance win. The browser still needs to resolve the CDN host, establish a connection and download the requested resource.

• Load only required packages.
• Use minified production files when available.
• Avoid loading large libraries for small features.
• Use appropriate script loading strategies.
• Prefer exact versions for predictable caching.
• Measure actual page performance instead of assuming a CDN is faster.

Common UNPKG Mistakes

• Using an unversioned package URL for a critical production dependency.
• Assuming every npm package can run directly in a browser.
• Guessing the file path inside a package.
• Loading a development build when a production build is available.
• Adding unnecessary third-party libraries.
• Ignoring the security implications of external JavaScript.
• Treating UNPKG as a replacement for npm dependency management.

Best Practices for Using UNPKG

• Use HTTPS URLs.
• Pin important dependencies to exact versions.
• Verify that the requested package actually supports browser usage.
• Use production and minified builds when appropriate.
• Request only the required files.
• Consider Subresource Integrity for fixed third-party resources.
• Keep external dependencies to a reasonable minimum.
• Use a package manager for applications that require full dependency management.
• Test CDN dependencies as part of the application's normal deployment process.

Frequently Asked Questions

Helpful Web Tools

An UNPKG URL Builder helps create package CDN URLs by selecting the package, version and file path. A jsDelivr URL Builder generates jsDelivr package URLs, a CDN URL Generator helps construct general CDN resource URLs, a Package.json Validator checks package metadata structure, and a URL Builder helps create URLs from their individual components.

Conclusion

UNPKG provides a simple way to deliver files from npm packages through a global CDN. By placing a package name, version and optional file path into a URL, developers can make public package resources available directly to browsers without hosting those files themselves.

The service is especially useful for static websites, prototypes, documentation and browser examples. For production applications, versioning should be handled carefully and security, performance and external service dependencies should be considered. When a project needs full dependency resolution, bundling and reproducible builds, a package manager such as npm, Yarn or pnpm is usually a better foundation.