Cloudflare Forge and Voxgig, compared

Why Cloudflare is 34 Voxgig SDKs

Cloudflare's API is one OpenAPI document of 26 MB: 2,260 paths, 3,605 operations and 6,926 schemas, in cloudflare/api-schemas. Generated as one Voxgig SDK, it would produce more than 100 MB of model JSON, past GitHub's 100 MB limit for a single file.

So the Voxgig build splits the definition by product area into 34 slices, each a complete OpenAPI document of its own, and generates an SDK from each. Every operation is in exactly one slice, and together the slices cover all 2,260 paths and 3,605 operations. The split is a script run over one commit of the definition, so anyone can repeat it.

The DNS SDK stands in for all 34 here. At 76 operations it sits in the middle of the slices, which run from 12 to 303, and it covers one product end to end. Each slice is its own SDK with its own client, so an application that uses DNS and Workers takes two, where Cloudflare's SDK is one client for everything.

What each SDK does

What the code is

The same calls in each, in TypeScript. Both samples type-check under strict mode against the SDK they name.

// cf imports its SDK through a package-private alias. Nothing outside cf can.
import { CloudflareApiClient } from '#sdk'

const client = new CloudflareApiClient({ apiToken: process.env.CLOUDFLARE_API_TOKEN })

const page = await client.dns.records.list({ zone_id: 'zone_123', per_page: 100 })
const record = await client.dns.records.get({ zone_id: 'zone_123', dns_record_id: 'rec_123' })
const created = await client.dns.records.create({
  zone_id: 'zone_123',
  body: { type: 'A', name: 'www.example.com', content: '198.51.100.4', ttl: 3600, proxied: false },
})
await client.dns.records.delete({ zone_id: 'zone_123', dns_record_id: 'rec_123' })

import { CloudflareDnsSDK } from '@voxgig-sdk/cloudflare-dns-sdk'

// The generated auth sends the key as X-Auth-Email, so switch it off and send
// the API token as a plain header.
const client = new CloudflareDnsSDK({
  auth: null,
  headers: { authorization: 'Bearer ' + process.env.CLOUDFLARE_API_TOKEN },
})

const records = await client.DnsRecord().list({ zone_id: 'zone_123' })
const record = await client.DnsRecord().load({ zone_id: 'zone_123', id: 'rec_123' })
// DnsRecordCreateData is the response envelope, so the record's own fields
// need a cast.
const created = await client.DnsRecord().create({
  zone_id: 'zone_123',
  type: 'A',
  name: 'www.example.com',
  content: '198.51.100.4',
  ttl: 3600,
  proxied: false,
} as any)
await client.DnsRecord().remove({ zone_id: 'zone_123', id: 'rec_123' })

What building and running both found

• Cloudflare's SDK is Fern's TypeScript output. Forge's transformer repairs the definition, patches Fern's Docker image, runs it in three shards and adds two runtime files, one of which unwraps Cloudflare's response envelope.
• It is private to the cf CLI: bundled and minified, with no export and no type declarations. The public Cloudflare SDKs Forge is meant to produce were not out on the checked date.
• Its DNS record type holds only the metadata half of the record schema, an allOf that Fern generated in part, so record.name, type and content do not compile, although the values are there at run time.
• Voxgig's model misses Cloudflare's envelope for 74 of the 76 DNS operations. List reads 0 records, load and create return the envelope, and the create type asks for result instead of the record's fields.
• Voxgig's auth takes the first scheme of the definition's first security requirement, X-Auth-Email, which carries an email address, not a key. A user following the README gets a 401.
• The 34 Cloudflare SDKs include only the test feature, so none of them retries, times out or logs. The eight other pairs on this site show what the standard set adds.
• Voxgig has no method for the record PATCH, because apidef models a PATCH beside a PUT as a sixth operation and sdkgen generates five. Cloudflare's SDK calls it edit.