How Do You Use jsDelivr to Load npm and GitHub Files via CDN?

Updated

Use jsDelivr by building a URL in the form https://cdn.jsdelivr.net/npm/package@version/file for npm packages, or https://cdn.jsdelivr.net/gh/user/repo@version/file for GitHub repositories. Pin an exact version for production, point the path at a real file inside the package, and expect the CDN to serve it from its global network. This works for any file type the package publishes, not just JavaScript.

The npm URL pattern

The core pattern is:

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

A concrete example from jsDelivr's own documentation loads jQuery 3.6.4:

https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js

Break that down:

  • npm tells jsDelivr the source is the npm registry.
  • jquery is the package name.
  • @3.6.4 pins the version.
  • /dist/jquery.min.js is the file path inside the published package.

The path must match what the package actually publishes. If you guess a path that doesn't exist, you get a 404 rather than a fallback.

Version pinning vs. ranges

jsDelivr accepts several version forms, and the choice matters for stability.

Form Example Behavior Use in production?
Exact version [email protected] Always serves that release Yes
Version range [email protected] Serves the latest 3.6.x Only if you accept patch drift
Major range jquery@3 Serves the latest 3.x Risky
Omitted jquery Serves the latest release No

jsDelivr's documentation explicitly warns against omitting the version in production, because the "latest" pointer moves whenever a new release is published. A range like @3.6 is a middle ground: you get bug fixes without a major-version jump, but the exact bytes can change between deploys.

Finding the right file

Three conveniences help when you don't know the exact path.

Minified variants. Append .min to any JS or CSS file to get a minified version. If the package doesn't ship one, jsDelivr generates it:

https://cdn.jsdelivr.net/npm/[email protected]/src/core.min.js

Default entry file. Omit the file path to get the package's default file:

https://cdn.jsdelivr.net/npm/[email protected]

Directory listing. Add a trailing slash to browse what's available:

https://cdn.jsdelivr.net/npm/jquery/

For programmatic discovery, the jsDelivr data API exposes entry points, versions, and file lists. For example, https://data.jsdelivr.com/v1/packages/npm/[email protected]/entrypoints returns the suggested entry file per file type, which is useful when a package's main file isn't obvious.

Loading GitHub files

GitHub-hosted files follow the same logic with a gh prefix:

https://cdn.jsdelivr.net/gh/<user>/<repo>@<version>/<file path>

The version can be a tag, a branch name, or a commit hash. Tags and commit hashes are stable; branch names move as the branch advances, so treat them like unpinned versions. The file path is relative to the repository root, so you reference the source file as committed, not a build artifact unless the repo commits one.

Combining and minifying on demand

jsDelivr can merge multiple files into one request by listing them after a combine path, and it minifies files on request as described above. This is handy for pulling several small modules or stylesheets in a single HTTP request. The trade-off is that a combined URL is a single point of failure: if one listed file is missing or renamed, the whole request breaks, so re-check combined URLs after dependency upgrades.

Troubleshooting common failures

404 on a file that exists locally. The published package may exclude that path (many packages ship only dist/ or only src/). Check the directory listing or the data API's file list to see what's actually published.

Wrong file served after an upgrade. You're probably using a range or an omitted version. Pin the exact version to lock the bytes.

Stale content after a fix. CDN caches hold files for a period, and jsDelivr offers a purge cache tool for exactly this case. Purging is the documented remedy when you've republished a version and need the edge to fetch it again. Note that republishing the same version is generally discouraged; publishing a new version is cleaner.

A file that works in one form but not another. Minified generation and default-file resolution depend on the package's contents. If .min generation or the default entry behaves unexpectedly, fall back to the explicit file path.

A quick checklist before going live

  1. Pin exact versions for every production URL.
  2. Confirm each path against the directory listing or data API.
  3. Prefer .min for JS and CSS to cut transfer size.
  4. Avoid branch names and omitted versions in production.
  5. Keep the purge cache tool bookmarked for republished assets.

Following these steps gives you a stable, cache-friendly way to serve npm and GitHub files without bundling them yourself.