cloudflare-typescript

Cloudflare’s official TypeScript library provides typed, promise-based access to the entire Cloudflare REST API from Node.js, Deno, Bun, and browser environments. It is generated directly from Cloudflare’s OpenAPI specification using Stainless, so every one of the API’s 2,500+ endpoints — zones, DNS, Workers, R2, D1, WAF, Zero Trust, AI Gateway, and more — ships with matching request and response types, kept automatically in sync as Cloudflare’s API evolves.

Beyond raw type coverage, the client handles the practical concerns of talking to a large REST API: automatic retries with exponential backoff for transient and rate-limit errors, configurable timeouts, cursor- and offset-based auto-pagination via async iterators, streaming file uploads, and a tree-shakable import path so bundles only include the resource classes actually used.

What You Get

• Typed client classes for all ~2,500 Cloudflare API endpoints (zones, DNS, Workers, R2, D1, WAF, Zero Trust, AI Gateway, and more), generated from the official OpenAPI spec
• Automatic retry, timeout, and cursor/offset auto-pagination handling built into every resource method
• A tree-shakable import path (cloudflare/tree-shakable) plus a bundled CLI (bin/cli) for bundle-size-sensitive or scripted use
• Exported TypeScript types for every request param and response shape, with docstrings that surface in editor hovers
• File upload helpers accepting File, fetch Response, fs.ReadStream, or a bundled toFile utility for endpoints like KV values and R2 objects

Common Use Cases

• Zone and DNS automation as part of infrastructure-as-code pipelines
• Workers/Pages deployment tooling that provisions KV namespaces, D1 databases, and R2 buckets
• Zero Trust and WAF policy management from internal admin tools instead of the dashboard
• Multi-tenant SaaS platforms provisioning per-customer zones, custom hostnames, and SSL certificates at signup
• Internal analytics dashboards built on top of Cloudflare’s Analytics endpoints

Under The Hood

Architecture The client is a single Cloudflare class (src/client.ts, ~1,800 lines) that wires together roughly 200 per-resource modules under src/resources/, each extending a shared APIResource base (src/resource.ts). Requests flow through core/api-promise.ts, which wraps the underlying fetch call in an APIPromise exposing .asResponse()/.withResponse(), while core/pagination.ts supplies several pagination strategies (cursor, cursor-after, single-page, V4 array) that resource methods return directly. Platform differences (Node, Deno, Bun, browser) are isolated behind internal/shims.ts and internal/detect-platform.ts. A separate tree-shakable.ts entry point builds partial clients from an explicit list of resource classes, so changing core plumbing affects every resource uniformly while individual resource modules stay independent of each other.

Tech Stack Written in TypeScript 5.8 with zero runtime dependencies ("dependencies": {} in package.json) — all HTTP, retry, and pagination logic is hand-rolled internally rather than pulled from third-party packages. Builds run through tsc-multi to emit CommonJS, ESM, and Deno-targeted output from one source tree; tests run under Jest with the SWC transform for speed. The package ships a bin/cli entry point and is published to npm as cloudflare via a Stainless-managed release pipeline.

Code Quality The repo carries an unusually large test suite for a client library — 871 auto-generated per-resource test files under tests/api-resources/ (one suite per API resource, exercising real request/response shapes) plus focused unit tests for base64 handling, header building, multipart form encoding, path building, query-string stringification, and file uploads. Errors are modeled as typed APIError subclasses (BadRequestError, AuthenticationError, RateLimitError, InternalServerError, etc.) mapped from HTTP status codes, with retry logic applied automatically to transient failures. CI runs on GitHub Actions with dedicated workflows for breaking-change detection and Semgrep security scanning in addition to the standard test/lint pipeline.

API Design The public surface favors resource-namespaced calls (client.zones.create(...)) over a single flat method list, keeping ~2,500 endpoints navigable via autocomplete. Auto-pagination works through for await...of on list methods or explicit hasNextPage()/getNextPage() control, retries and timeouts are configurable globally or per-call, and .asResponse()/.withResponse() give access to raw headers without extra plumbing. A companion api.md (10K+ lines) and MIGRATION.md document every method and version-to-version breaking change, which offsets the fact that the generated resource code itself is comment-sparse.