Getting started overview

jsDelivr is a free public content delivery network (CDN) designed for open-source projects. It offers a way to serve JavaScript files, CSS stylesheets, images, and other web assets directly from npm, GitHub, and WordPress repositories, bypassing the need for developers to host these files themselves. Unlike many commercial CDNs, jsDelivr does not require an account, API keys, or a complex setup process for its core content delivery functionality. This design choice prioritizes immediate usability for developers integrating open-source libraries and frameworks into their web applications.

The primary method for utilizing jsDelivr involves constructing a specific URL that points to the desired file within a supported open-source project. This URL pattern varies slightly depending on whether the asset originates from npm, GitHub, or WordPress. Once the correct URL is formed, it can be directly embedded into an HTML <script> tag, <link> tag, or other web resource references. jsDelivr handles the caching and delivery of these assets through a global network of servers, aiming to provide low-latency access to users worldwide.

This getting started guide focuses on the practical steps to quickly integrate jsDelivr into your projects, covering the essential URL structures and a first functional request. It outlines how to locate and reference common open-source assets without requiring any prior registration or authentication, consistent with jsDelivr's operational model.

Create an account and get keys

jsDelivr operates uniquely among CDN providers because it does not require user accounts or API keys for its primary function of serving open-source project files. This means there is no sign-up process, no dashboard to configure, and no credentials to manage for basic content delivery. The service is designed for immediate, public access to open-source assets.

Therefore, the steps typically associated with creating an account and obtaining API keys are not applicable to jsDelivr's core CDN offering. Developers can proceed directly to constructing URLs for the assets they wish to serve.

While jsDelivr itself does not require accounts, the underlying platforms it sources from (like npm or GitHub) do require accounts for publishing packages or repositories. However, these accounts are for the project maintainers, not for end-users consuming the content via jsDelivr. For instance, to publish a package to npm that jsDelivr would then host, a developer would need an npm account.

For advanced use cases, such as custom domain integration or private content delivery, other CDN providers often require accounts and API keys. However, jsDelivr's focus on public open-source content simplifies this aspect considerably, removing a common barrier to entry for developers.

Your first request

Making your first request with jsDelivr involves constructing a URL that points to a specific file within an open-source project. The most common use cases are serving files from npm packages, GitHub repositories, or WordPress plugins/themes. Below are examples for each, demonstrating how to integrate them into a basic HTML file.

npm Packages

To serve a file from an npm package, use the following URL structure:

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

  • package-name: The name of the npm package (e.g., jquery).
  • version: The specific version of the package (e.g., 3.6.0). You can also use ranges like ^3 for the latest 3.x.x, or omit entirely for the latest stable version.
  • file-path: The path to the file within the package (e.g., dist/jquery.min.js).

Example: jQuery

To include the minified jQuery library version 3.7.1 in your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>jsDelivr jQuery Example</title>
</head>
<body>
    <h1>Hello, jsDelivr!</h1>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
    <script>
        $(document).ready(function() {
            $('h1').text('jQuery Loaded Successfully!');
        });
    </script>
</body>
</html>

GitHub Repositories

To serve a file directly from a GitHub repository, use this structure:

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

  • user: The GitHub username or organization (e.g., twbs).
  • repo: The repository name (e.g., bootstrap).
  • version: A Git tag, commit hash, or branch name (e.g., v5.3.0 or main).
  • file-path: The path to the file within the repository (e.g., dist/css/bootstrap.min.css).

Example: Bootstrap CSS

To include Bootstrap CSS version 5.3.0:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>jsDelivr Bootstrap Example</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/twbs/[email protected]/dist/css/bootstrap.min.css">
</head>
<body>
    <div class="container mt-5">
        <h1 class="text-primary">Bootstrap via jsDelivr</h1>
        <button class="btn btn-success">Styled Button</button>
    </div>
</body>
</html>

WordPress Plugins/Themes

For WordPress assets, the structure is:

https://cdn.jsdelivr.net/wp/plugins/plugin-slug/version/file-path (for plugins)
https://cdn.jsdelivr.net/wp/themes/theme-slug/version/file-path (for themes)

  • plugin-slug or theme-slug: The slug of the plugin or theme from the WordPress directory (e.g., contact-form-7).
  • version: The specific version number.
  • file-path: The path to the file within the plugin/theme directory.

Example: Contact Form 7 CSS

To include a stylesheet from Contact Form 7 version 5.8.0:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>jsDelivr WordPress Example</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/wp/plugins/contact-form-7/5.8.0/includes/css/styles.css">
    <style>
        /* Custom styles to demonstrate Contact Form 7 CSS */
        body { font-family: sans-serif; }
        .wpcf7-form { border: 1px solid #ddd; padding: 20px; max-width: 500px; margin: 50px auto; }
    </style>
</head>
<body>
    <div class="wpcf7-form">
        <p>This content would typically be styled by Contact Form 7 CSS.</p>
    </div>
</body>
</html>

After saving these HTML files and opening them in a web browser, you should observe the assets being loaded and applied. For instance, the jQuery example will change the heading text, and the Bootstrap example will style the button and heading. The WordPress example will show a bordered box, assuming the Contact Form 7 styles are applied to the .wpcf7-form class.

This direct embedding approach is fundamental to jsDelivr's utility, allowing developers to quickly integrate external libraries without local hosting or complex build processes. For more detailed URL construction options and features like combining files, refer to the jsDelivr API documentation.

Common next steps

Once you are comfortable making basic requests with jsDelivr, several common next steps can enhance your usage and project integration:

  1. Version Management: While specific versions (e.g., [email protected]) offer stability, jsDelivr supports various version aliases:

    • Major version: @3 will load the latest 3.x.x version.
    • Minor version: @3.7 will load the latest 3.7.x version.
    • Latest: Omitting the version (e.g., /npm/jquery/dist/jquery.min.js) will load the absolute latest stable version. Use this with caution in production, as it can introduce breaking changes.

    Understanding these options allows for flexible management of dependencies, balancing stability with access to the newest features. For critical production environments, pinning to a specific version is often recommended to prevent unexpected updates.

  2. Combine Multiple Files: jsDelivr allows combining multiple JavaScript or CSS files into a single request, reducing HTTP requests. This is achieved by separating file paths with a comma:

    <script src="https://cdn.jsdelivr.net/combine/npm/[email protected],npm/[email protected]/dist/js/bootstrap.bundle.min.js"></script>

    This feature is particularly useful for optimizing page load times by consolidating multiple small asset files into a single download. It's important to ensure the combined files are compatible and ordered correctly if they have dependencies on each other.

  3. SRI (Subresource Integrity): To enhance security, especially when loading resources from external CDNs, it is recommended to use Subresource Integrity. SRI allows browsers to verify that fetched resources have not been tampered with. You can generate SRI hashes for jsDelivr URLs directly from their website or use tools.

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"
        integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo="
        crossorigin="anonymous"></script>

    Implementing SRI provides a crucial security layer, ensuring that the content delivered by the CDN matches the expected cryptographic hash. This protects against potential supply chain attacks where a CDN might be compromised.

  4. Explore Other CDNs: While jsDelivr is excellent for open-source projects, other CDNs like Cloudflare CDN or Amazon CloudFront offer broader features for private content, custom domains, and more advanced configurations. Understanding their capabilities can help you choose the right solution for different project needs.

  5. Local Development: For local development, consider using package managers like npm or yarn to install dependencies locally. This provides offline access and allows for easier integration with build tools (e.g., Webpack, Rollup) that bundle and optimize assets. jsDelivr is primarily for production deployment or quick prototyping where local installation is not desired.

  6. Advanced Features: Explore jsDelivr's advanced features such as arbitrary file hosting (for GitHub repositories), raw content delivery, and the API for programmatic access to package information. These features offer greater control and flexibility for specific use cases beyond simple file inclusion.

Troubleshooting the first call

If your first request to jsDelivr isn't working as expected, consider these common issues and troubleshooting steps:

  1. Incorrect URL Path: This is the most frequent cause of issues. Double-check the path to the file within the package or repository. Many npm packages have their main files in a dist/ or build/ directory. For GitHub, ensure the path reflects the exact file structure in the repository.

    • Solution: Visit the npm package page or GitHub repository on the respective platforms to verify the correct file path. For example, for a jQuery file, navigate to the dist folder in the GitHub repository to see the exact file name.

  2. Incorrect Version Number: Using a non-existent version or an incorrectly formatted version number will lead to a 404 error.

    • Solution: Check the npm registry for available versions of a package (npmjs.com) or the GitHub repository's releases/tags section. Ensure the version matches exactly.

  3. Typographical Errors: A simple typo in the package name, username, repository name, or file path can prevent the resource from loading.

    • Solution: Carefully review your URL for any misspellings. Copy-pasting from the official source is often the safest approach.

  4. Network Issues: Local network problems or temporary CDN outages can prevent resources from loading.

    • Solution: Check your internet connection. You can also visit jsDelivr's status page (if available) or check general CDN status monitoring sites. Try accessing the jsDelivr URL directly in your browser to see if the file loads.

  5. Browser Developer Console Errors: The browser's developer console (usually accessed by F12) will often provide specific error messages, such as 404 Not Found for incorrect URLs or CORS errors if there are cross-origin issues (though less common with jsDelivr for public assets).

    • Solution: Open the console and look for red error messages in the Network or Console tabs. These messages can pinpoint the exact problem, such as a missing file or a failed request.

  6. Caching: Sometimes, outdated browser or CDN cache can cause issues, especially after updating a file or version.

    • Solution: Clear your browser cache or perform a hard refresh (Ctrl+F5 or Cmd+Shift+R). jsDelivr's CDN cache typically refreshes quickly, but in rare cases, propagation delays might occur.

  7. File Not Publicly Accessible (GitHub): If you're linking to a GitHub repository, ensure the file is part of a public repository and branch. Private repositories or files not committed to a public branch will not be accessible via jsDelivr.

    • Solution: Verify the repository and the specific file are publicly visible on GitHub.

Quick Reference: Getting Started with jsDelivr

Step What to Do Where
1. Identify Asset Determine the open-source library, framework, or file you need. npm registry, GitHub repository, WordPress plugin directory
2. Find Version & Path Locate the exact version number and the file's path within the project. Project's official documentation, npmjs.com, GitHub repo file browser
3. Construct URL Build the jsDelivr URL using the appropriate pattern (npm, GitHub, or WP). jsDelivr documentation for URL patterns
4. Embed in HTML Place the constructed URL into your HTML (e.g., <script src="..."> or <link href="...">). Your HTML file or web application
5. Test Open your web page in a browser and check the developer console for errors. Web browser (F12 for developer tools)