cdnjs moves to Workers KV and drops its origin servers

Cloudflare has migrated cdnjs—the open-source CDN for JavaScript libraries—to a serverless architecture built on Cloudflare Workers and Workers KV. The change removes the physical origin machines that previously served cdnjs files, replacing them with a globally distributed key-value store that serves content directly from Cloudflare's edge network.

cdnjs is a significant piece of internet infrastructure. It serves JavaScript, CSS, and other web libraries to over 11% of websites, handling roughly 190 billion requests and 3.46PB of data in July alone. For users, it means fetching a popular library like jQuery from a nearby data center in around 20ms instead of enduring 300ms-plus round trips to a distant origin.

The old architecture and its pain points

Historically, cdnjs files lived in a GitHub repository. Load-balanced machines at a single Cloudflare core data center periodically pulled from that backing store and acted as the origin for cdnjs.cloudflare.com. Cloudflare's cache would then serve files from edge locations after the first request.

That model created friction for contributors and maintainers alike. Adding a library meant opening a pull request against a repo that was roughly 300GB—a practical obstacle for casual contributors. Cloning it required serious disk space and, depending on your filesystem, could fail outright: macOS's case-insensitive default made the repo effectively uncloneable without extra workarounds.

Maintainers faced their own burden. Contributors could submit version files directly, which meant every file had to be manually diffed against official library sources and scanned for malware. Updates were driven by an optional auto-update definition in each package's JSON file; when present, a bot would fetch new releases from npm or GitHub, push files to the repo, and compute Subresource Integrity (SRI) hashes. If that definition was missing, someone had to file manual pull requests for every new version.

An April incident underscored the fragility of the setup. During maintenance at a core data center, a technician accidentally disconnected cables linking it to other facilities, taking the center offline for roughly four hours. That data center housed cdnjs's primary origin servers; only Cloudflare's global cache prevented a complete outage, with uncached assets failing to load.

Why Workers KV fit

cdnjs files are write-once, read-often assets—exactly the workload Workers KV is designed for. The team realized that storing files in Workers KV would eliminate physical machines entirely, distributing data worldwide and making cdnjs resilient to any single data center failure.

One wrinkle emerged: Workers KV has a 10MiB value limit, and several hundred of cdnjs's 7 million-plus assets exceeded it, mostly JavaScript Source Maps. The solution was to compress files before storing them.

All cdnjs files are now written to Workers KV in both Brotli and gzip forms, using higher compression levels than on-the-fly compression allows. This solves the size problem and reduces bandwidth consumption—files are served both smaller and faster.

New contribution and serving pipeline

The contribution flow has been rebuilt around a new repository, cdnjs/packages, which is easily cloneable at around 50MB. It holds thousands of JSON files, each describing a package and how it auto-updates from npm or git.

Security and maintainability improvements are baked into the new process:

  • Version files are now created by an automated bot rather than submitted directly by humans, minimizing malicious or error-prone contributions.
  • Human-submitted JSON files are validated against a JSON schema and checked for popularity on npm or GitHub before a maintainer approves them.
  • When the bot detects a new release, it pushes compressed files to a files namespace in Workers KV, along with metadata for ETag and Last-Modified HTTP headers.
  • SRI hashes of the uncompressed files are computed by the bot and stored in a separate SRIs namespace in Workers KV.

When a client requests a file from cdnjs.cloudflare.com, a Cloudflare Worker inspects the Accept-Encoding header and retrieves the matching compressed version from Workers KV. The response is cached at the edge for subsequent requests, with on-the-fly decompression applied if needed.

A small number of files still exceed Workers KV's value limit. For those, the Worker falls back to an origin backed by the original git repo—infrastructure the team plans to phase out in the coming months.

Website and API upgrades

The cdnjs project's other components were upgraded alongside the core file-serving infrastructure.

The homepage now points to a beta website built with Vue and Nuxt. It runs entirely on the client side after the first page load, is powered by the cdnjs API, and always reflects the latest package information.

The cdnjs API itself moved to a serverless architecture similar to the main cdnjs setup. Previously, it relied on a scheduled job generating roughly 300MB of metadata that the API backend would load into memory to answer requests. File SRIs were similarly cloned from GitHub into local storage.

That approach became unsustainable at scale—millions of reads and unreasonable processing times. The team split all metadata into four Workers KV namespaces: package-level metadata, version-specific metadata, aggregated metadata, and file SRIs. A Cloudflare Worker now serves metadata.speedcdnjs.com from these namespaces via several public endpoints, with the cdnjs API fully integrated.

Transparency and future direction

cdnjs has been open-source since its founding in January 2011, and Cloudflare has maintained that posture since partnering with founders Ryan Kirkman and Thomas Davis in June of that year. After years of the project struggling with limited maintainer resources, Cloudflare took on a larger role last year, and the project now counts active maintainers from both Cloudflare and the community.

One concern with the move to Workers KV is that the distributed store is not itself open-source, potentially making cdnjs's operation less auditable. To address this, the team introduced cdnjs/logs, a repository where the bot logs all Workers KV-related events. Anyone can also fetch SRIs from the cdnjs API to verify the integrity of files.

The migration resolves the reliability and maintainability problems exposed over the past year. Files now live at the edge rather than on single-location physical machines, contribution is easier for the community, and maintainers have shifted from manually inspecting files to overseeing a validated, bot-driven pipeline. Cloudflare says it will publish further posts as the remaining legacy infrastructure is retired.