How jsDelivr Works

jsDelivr is a public content delivery network that allows developers to load files from popular package and repository sources through CDN URLs. It is commonly used to deliver JavaScript libraries, CSS files, images, fonts and other static assets directly to web browsers without requiring the website owner to host those files.

One of the most common uses of jsDelivr is serving files from npm packages. A developer can reference a package and version in a URL, optionally specify a file inside that package, and let jsDelivr deliver the resource through its distributed CDN infrastructure.

jsDelivr can also serve files from GitHub repositories. This makes it useful not only for npm-based JavaScript dependencies but also for distributing public files stored in source repositories.

What Is jsDelivr?

jsDelivr is a free public CDN designed primarily for developers and open-source projects. It provides a simple URL-based way to request files from supported package and repository sources.

Instead of downloading a library manually and hosting it on your own server, a website can reference a jsDelivr URL. The browser requests that URL, jsDelivr handles the CDN delivery and the requested file is returned to the browser.

Browser
   ↓
jsDelivr URL
   ↓
CDN edge server
   ↓
Cached file
   ↓
Browser

What Can jsDelivr Serve?

jsDelivr can be used to deliver many types of static files from supported sources. The exact files available depend on the package or repository being requested.

• JavaScript files.
• CSS stylesheets.
• JSON files.
• Images and icons.
• Web fonts.
• Source maps.
• Package metadata.
• Other public static files contained in supported packages or repositories.

How jsDelivr Works

When a browser requests a jsDelivr URL, the request is handled by the CDN rather than directly by the npm registry or GitHub repository. jsDelivr determines which resource the URL represents and retrieves or serves the corresponding file through its CDN infrastructure.

Website
   ↓
Browser requests jsDelivr URL
   ↓
jsDelivr CDN
   ↓
Check cached resource
   ↓
Cache HIT → return file
   ↓
Cache MISS → retrieve source file
   ↓
Cache resource
   ↓
Return file to browser

The important idea is that the browser does not need to communicate with the original package source for every request. Once a resource is available through the CDN cache, subsequent requests can often be served directly from the CDN.

jsDelivr and npm

One of jsDelivr's most popular features is its integration with npm packages. Developers can reference a published npm package by name and optionally specify its version and a particular file.

https://cdn.jsdelivr.net/npm/package@version/file

For example, a URL can identify a package called example-package, a specific version and a JavaScript file inside that package.

https://cdn.jsdelivr.net/npm/example-package@1.2.3/dist/index.min.js

Using a Specific npm Package Version

A jsDelivr npm URL can specify an exact package version. This is useful when a website needs a predictable dependency and should not automatically start using a newer package release.

<script src="https://cdn.jsdelivr.net/npm/example-package@1.2.3/dist/index.min.js"></script>

The version becomes part of the resource URL. This makes different package versions distinct CDN resources and provides a clear reference to the dependency version used by the page.

Using the Latest Version

A package URL can also be written without an explicit version. In that case, jsDelivr can resolve the package to the version associated with the current package metadata rather than keeping the URL permanently tied to one version.

https://cdn.jsdelivr.net/npm/example-package/file.js

Specifying a File

npm packages often contain many files, including source code, compiled distributions, documentation and metadata. A jsDelivr URL can point to a particular file within the package.

https://cdn.jsdelivr.net/npm/package@1.2.3/dist/package.min.js

The exact path depends on the package structure. Some packages provide files inside directories such as dist or lib, while others expose a different layout.

Package Root URLs

A package URL does not always have to point directly to a specific JavaScript file. Depending on the request, the package root can be used to inspect or resolve package contents and metadata.

For practical website usage, however, developers normally request the exact asset required by the page rather than depending on a package root response.

jsDelivr and GitHub

In addition to npm, jsDelivr can deliver files from public GitHub repositories. This allows developers to create CDN URLs for files stored in GitHub without configuring a separate static hosting server.

https://cdn.jsdelivr.net/gh/user/repository@version/path/to/file

The URL identifies the GitHub user or organization, repository, optional reference such as a branch, tag or commit, and the path to the requested file.

GitHub URL Example

https://cdn.jsdelivr.net/gh/example-user/example-project@v1.0.0/dist/app.min.js

This type of URL can be useful for distributing public assets maintained in a GitHub repository. Using a tag or commit reference can also make the requested version more predictable than relying on a moving branch.

npm CDN vs GitHub CDN

The choice depends on where the resource is maintained. npm is generally convenient when a project is already distributed as a package, while GitHub delivery is useful when the desired file exists directly in a public repository.

jsDelivr CDN Caching

jsDelivr uses CDN caching to distribute frequently requested resources efficiently. When a resource is already cached at an appropriate edge location, it can be served without retrieving the original file again for every request.

First request
Browser → CDN → Source
                  ↓
               Resource
                  ↓
                Cache

Later request
Browser → CDN Cache → Resource

Caching is one of the main reasons a public CDN can efficiently serve the same open-source asset to users around the world. Popular resources can be requested repeatedly while the CDN handles delivery from its distributed infrastructure.

What Happens on a Cache MISS?

When the requested resource is not available as a usable cached copy at the relevant CDN location, jsDelivr may need to retrieve it from its source. After the resource becomes available to the CDN, it can be cached according to the service's delivery and caching behavior.

Why CDN Caching Is Important

Without caching, a public CDN would need to repeatedly retrieve the same resource from its source systems. Caching reduces unnecessary origin requests and allows frequently requested files to be distributed efficiently.

Caching can also reduce latency because users can receive resources from CDN infrastructure located closer to their network location than the original package or repository source.

jsDelivr and Versioned Assets

Versioned URLs are especially useful with CDN caching. When the URL contains an exact package version, the URL identifies a specific resource rather than a moving dependency reference.

Version 1:
https://cdn.jsdelivr.net/npm/example-package@1.0.0/dist/app.js

Version 2:
https://cdn.jsdelivr.net/npm/example-package@2.0.0/dist/app.js

These URLs refer to different versions and can coexist as separate resources. This makes versioned CDN URLs well suited to immutable-style asset delivery.

Branches, Tags and Commits

GitHub-based jsDelivr URLs can reference repository versions such as branches, tags or commits. These references have different stability characteristics.

jsDelivr and Website Performance

Using jsDelivr can improve delivery of public static assets because the files are distributed through CDN infrastructure instead of being served directly from the website's origin server. The benefit is particularly noticeable when users are geographically distributed.

However, adding a CDN does not automatically make every page faster. The browser still has to establish connections, download the requested resources and execute JavaScript. A page with too many external dependencies can still become slower even when those dependencies are delivered through a fast CDN.

Avoid Loading Unnecessary Dependencies

A CDN makes it easy to add public libraries to a webpage, but convenience should not replace dependency management. Loading several large libraries simply because they are available through a CDN can increase page weight and execution time.

• Load only the libraries the page actually needs.
• Prefer production builds when available.
• Use minified assets where appropriate.
• Remove unused dependencies.
• Monitor JavaScript bundle and network sizes.
• Choose versions intentionally.

jsDelivr vs UNPKG

jsDelivr and UNPKG are both commonly used to serve files from npm packages, but they are different services with different infrastructure and URL conventions. Both can be useful for browser-based projects that need to reference public package files through a CDN.

The best choice depends on the project's requirements, existing infrastructure and preferred URL format. Neither service should be treated as a universal replacement for package management or self-hosted application assets.

jsDelivr vs GitHub Raw URLs

GitHub provides ways to access raw repository files, while jsDelivr provides CDN-oriented delivery for supported GitHub content. A raw GitHub URL is primarily a direct repository file reference, whereas a jsDelivr URL is designed to deliver the resource through CDN infrastructure.

Using jsDelivr in HTML

A JavaScript file hosted through jsDelivr can be included in an HTML document with a normal script element.

<script src="https://cdn.jsdelivr.net/npm/example-package@1.2.3/dist/example.min.js"></script>

CSS resources can similarly be referenced with a stylesheet link when the package provides a CSS file.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/example-package@1.2.3/dist/example.min.css"
/>

Subresource Integrity

When loading third-party browser resources, Subresource Integrity, or SRI, can allow a browser to verify that a fetched resource matches an expected cryptographic hash. This provides protection against unexpected changes to the referenced file.

<script
  src="https://cdn.example.com/library.min.js"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>

SRI is most practical when the referenced resource is expected to remain byte-for-byte identical. Changing the file requires updating the corresponding integrity value.

Does jsDelivr Host Your Files?

jsDelivr is not a general-purpose personal file hosting service. It delivers supported public content from package and repository sources. The original project still belongs to the source ecosystem, such as an npm package or public GitHub repository.

Does jsDelivr Replace npm?

No. npm and jsDelivr serve different purposes. npm is primarily a package registry and ecosystem used to publish, install and manage JavaScript packages. jsDelivr provides CDN delivery for supported package content.

A package can be installed with npm during development while a specific public asset can also be delivered through jsDelivr. The two approaches are not mutually exclusive.

When Should You Use jsDelivr?

jsDelivr is particularly useful for simple websites, prototypes, documentation, demos and other projects that need public static assets without maintaining their own asset hosting infrastructure.

• Loading a small JavaScript library in a static HTML page.
• Including a public CSS framework.
• Testing a package quickly in a browser.
• Serving a public asset from GitHub.
• Creating examples and documentation demos.
• Delivering versioned open-source resources.

When Should You Avoid Direct CDN Dependencies?

A direct CDN dependency is not always the best choice for a large production application. Projects with a build system often benefit from installing dependencies through a package manager, bundling the required code and controlling exactly what is shipped to the browser.

Direct CDN usage can also introduce an external dependency that is outside the application's own deployment process. Teams should consider availability, versioning, security and operational requirements before depending on an external CDN for critical application functionality.

Common jsDelivr Mistakes

• Using an unversioned package URL without considering future updates.
• Guessing a file path instead of checking the package contents.
• Loading development builds instead of optimized production files.
• Adding too many third-party libraries to a page.
• Using a changing GitHub branch for a resource that should remain stable.
• Ignoring third-party dependency security.
• Assuming CDN delivery eliminates the need for application performance optimization.

Best Practices for jsDelivr

• Use HTTPS URLs.
• Pin production npm dependencies to known versions.
• Use stable GitHub references for production assets.
• Request only the files that are actually required.
• Prefer minified production assets when available.
• Consider Subresource Integrity for suitable third-party resources.
• Keep the number of external dependencies under control.
• Review dependency updates before changing production URLs.
• Use a package manager when the project requires full dependency management.

Frequently Asked Questions

Helpful Web Tools

A jsDelivr URL Builder helps create npm and GitHub CDN URLs without manually constructing every URL component. A CDN URL Generator helps build general CDN resource URLs, a UNPKG URL Builder creates URLs for npm packages served through UNPKG, a GitHub Raw URL Builder generates direct URLs for repository files, and a URL Builder helps construct URLs from their individual parts.

Conclusion

jsDelivr is a developer-focused CDN that makes it easy to deliver public files from npm packages and GitHub repositories. Its URL-based approach allows websites to reference JavaScript, CSS and other static assets without hosting those files directly.

The basic model is simple: identify the source, package or repository, select the desired version and file, and let jsDelivr handle CDN delivery and caching. For reliable production usage, version dependencies explicitly, use stable repository references, avoid unnecessary external resources and consider security mechanisms such as Subresource Integrity when appropriate.