Migrating to v6

Guide for migrating from v5 to v6 of the Cloudflare TypeScript SDK

v6.0.0-beta.1 is currently in Beta. Please test thoroughly before deploying to production.

Version 6 introduces significant breaking changes primarily due to OpenAPI specification updates and improved code generation. This guide will help you migrate from v5 to v6 successfully.

Overview

The v6 release includes:

• Type safety improvements with discriminated unions
• Parameter requirement changes across multiple services
• Interface renames and restructuring
• Removal of deprecated features
• New pagination patterns

Most breaking changes stem from OpenAPI definition updates that improve type safety and API accuracy. Take time to review each section relevant to your implementation.

Breaking changes by service

Addressing

Parameter requirement changes

Several parameters have changed from optional to required, or had their types refined:

BGPPrefix and ServiceBinding changes

// Before (v5)
await client.addressing.prefixes.bgp.create({
  account_id: 'abc123',
  // cidr was optional
});

// After (v6)
await client.addressing.prefixes.bgp.create({
  account_id: 'abc123',
  cidr: '203.0.113.0/24', // now required
});

Changes:

• BGPPrefixCreateParams.cidr: optional → required
• PrefixCreateParams.asn: number | null → number
• PrefixCreateParams.loa_document_id: required → optional
• ServiceBindingCreateParams.cidr: optional → required
• ServiceBindingCreateParams.service_id: optional → required

API Gateway

Type renames and parameter changes improve consistency:

// Before (v5)
import { PublicSchema, SchemaUpload } from 'cloudflare';

// After (v6)
import { OldPublicSchema, UserSchemaCreateResponse } from 'cloudflare';

Changes:

• ConfigurationUpdateResponse removed
• PublicSchema → OldPublicSchema
• SchemaUpload → UserSchemaCreateResponse
• ConfigurationUpdateParams.properties removed; use normalize instead

CloudforceOne

Response type changes for bulk operations:

Bulk create response structure

// Before (v5)
const result: number = await client.cloudforceOne.threatEvents.bulkCreate({
  // ...
});

// After (v6)
const result = await client.cloudforceOne.threatEvents.bulkCreate({
  // ...
});
// Returns: { counts: {...}, errors: [...] }

The response is now a complex object with counts and errors fields instead of a simple number.

D1 Database

Query parameter types now support batch operations:

// Before (v5)
await client.d1.database.query(dbId, {
  sql: 'SELECT * FROM users',
});

// After (v6) - Single query
await client.d1.database.query(dbId, {
  sql: 'SELECT * FROM users',
});

// After (v6) - Batch queries
await client.d1.database.query(dbId, {
  batch: [
    { sql: 'SELECT * FROM users' },
    { sql: 'SELECT * FROM posts' },
  ],
});

Changes:

• DatabaseQueryParams: simple interface → union type (D1SingleQuery | MultipleQueries)
• DatabaseRawParams: same change
• Supports batch queries via batch array

DNS Records

All DNS record type interfaces have been renamed from long names to short codes:

DNS record type renames (21 types)

// Before (v5)
import { 
  RecordResponse.ARecord,
  RecordResponse.AAAARecord,
  RecordResponse.CNAMERecord 
} from 'cloudflare';

// After (v6)
import { 
  RecordResponse.A,
  RecordResponse.AAAA,
  RecordResponse.CNAME 
} from 'cloudflare';

Complete list of renames:

• ARecord → A
• AAAARecord → AAAA
• CNAMERecord → CNAME
• MXRecord → MX
• NSRecord → NS
• PTRRecord → PTR
• TXTRecord → TXT
• CAARecord → CAA
• CERTRecord → CERT
• DNSKEYRecord → DNSKEY
• DSRecord → DS
• HTTPSRecord → HTTPS
• LOCRecord → LOC
• NAPTRRecord → NAPTR
• SMIMEARecord → SMIMEA
• SRVRecord → SRV
• SSHFPRecord → SSHFP
• SVCBRecord → SVCB
• TLSARecord → TLSA
• URIRecord → URI
• OpenpgpkeyRecord → Openpgpkey

IAM Resource Groups

Field requirement changes:

// Before (v5)
const group = await client.iam.resourceGroups.create({
  // ...
});
// group.scope was optional single value
// group.id was optional

// After (v6)
const group = await client.iam.resourceGroups.create({
  // ...
});
// group.scope is required array
// group.id is required

Changes:

• ResourceGroupCreateResponse.scope: optional single → required array
• ResourceGroupCreateResponse.id: optional → required

Origin CA Certificates

Several optional parameters are now required:

// Before (v5)
await client.ssl.certificateAuthorities.originCaCertificates.create({
  // All parameters were optional
});

// After (v6)
await client.ssl.certificateAuthorities.originCaCertificates.create({
  csr: '-----BEGIN CERTIFICATE REQUEST-----...',
  hostnames: ['example.com'],
  request_type: 'origin-rsa',
  // All three parameters now required
});

Changes:

• OriginCACertificateCreateParams.csr: optional → required
• OriginCACertificateCreateParams.hostnames: optional → required
• OriginCACertificateCreateParams.request_type: optional → required

Pages

Type renames and domain field changes:

// Before (v5)
import { DeploymentsSinglePage } from 'cloudflare';

// After (v6)
import { DeploymentListResponsesV4PagePaginationArray } from 'cloudflare';

Changes:

• Renamed: DeploymentsSinglePage → DeploymentListResponsesV4PagePaginationArray
• Domain response fields: many optional → required

Pipelines

Major version upgrade from v0 to v1 API:

The entire v0 API is deprecated. You must migrate to v1 methods.

1. Update method names

   All Pipelines methods now have V1 suffix:

   // Before (v5)
   await client.pipelines.create({ /* ... */ });
   await client.pipelines.list();
   
   // After (v6)
   await client.pipelines.createV1({ /* ... */ });
   await client.pipelines.listV1();
   
2. Use new sub-resources

   v1 introduces new sub-resources for better organization:

   // Sinks
   await client.pipelines.sinks.create({ /* ... */ });
   await client.pipelines.sinks.list();
   await client.pipelines.sinks.delete(sinkId);
   await client.pipelines.sinks.get(sinkId);
   
   // Streams
   await client.pipelines.streams.create({ /* ... */ });
   await client.pipelines.streams.update(streamId, { /* ... */ });
   await client.pipelines.streams.list();
   await client.pipelines.streams.delete(streamId);
   await client.pipelines.streams.get(streamId);
   

R2

Parameter requirement changes:

// Before (v5)
await client.r2.buckets.eventNotifications.update(bucketName, {
  // rules was optional
});

// After (v6)
await client.r2.buckets.eventNotifications.update(bucketName, {
  rules: [/* ... */], // now required
});

Changes:

• EventNotificationUpdateParams.rules: optional → required
• Super Slurper: bucket, secret now required in source params

Radar

Typed enums and signature changes:

Enum type changes

// Before (v5)
const dataSource: string = 'cloudflare';
const eventType: string = 'attack';

// After (v6)
const dataSource: 'cloudflare' | 'apnic' | /* 21 more values */ = 'cloudflare';
const eventType: 'attack' | 'outage' | 'hijack' | /* 3 more values */ = 'attack';

Changes:

• dataSource: string → typed enum (23 values)
• eventType: string → typed enum (6 values)

V2 methods now require a dimension parameter, which is a breaking signature change.

Resource Sharing

Field removal:

// Before (v5)
const recipient = await client.resourceSharing.recipients.get(/* ... */);
console.log(recipient.status_message);

// After (v6)
const recipient = await client.resourceSharing.recipients.get(/* ... */);
// recipient.status_message no longer exists

Changes:

• Removed: status_message field from all recipient response types

Schema Validation

Response type consolidation:

// Before (v5)
import { 
  SchemaCreateResponse,
  SchemaListResponse,
  SchemaEditResponse,
  SchemaGetResponse 
} from 'cloudflare';

// After (v6)
import { PublicSchema } from 'cloudflare';
// All operations now return PublicSchema

Changes:

• Consolidated SchemaCreateResponse, SchemaListResponse, SchemaEditResponse, SchemaGetResponse → PublicSchema
• Renamed: SchemaListResponsesV4PagePaginationArray → PublicSchemasV4PagePaginationArray

Spectrum

Union member renames:

// Before (v5)
import { AppListResponse } from 'cloudflare';
type Config = AppListResponse.UnionMember0;

// After (v6)
import { SpectrumConfigAppConfig } from 'cloudflare';

Changes:

• AppListResponse.UnionMember0 → SpectrumConfigAppConfig
• AppListResponse.UnionMember1 → SpectrumConfigPaygoAppConfig

Workers

Type removals and renames:

// Before (v5)
import { 
  WorkersBindingKindTailConsumer,
  ScriptsSinglePage,
  DeploymentsSinglePage 
} from 'cloudflare';

// After (v6)
import { ScriptListResponsesSinglePage } from 'cloudflare';
// WorkersBindingKindTailConsumer removed
// DeploymentsSinglePage removed

Changes:

• Removed: WorkersBindingKindTailConsumer type
• Renamed: ScriptsSinglePage → ScriptListResponsesSinglePage
• Removed: DeploymentsSinglePage

Zero Trust DLP

Return type changes:

// Before (v5)
const dataset = await client.zeroTrust.dlp.datasets.create({ /* ... */ });

// After (v6)
const dataset = await client.zeroTrust.dlp.datasets.create({ /* ... */ });
// Return type structure has changed

Changes:

• datasets.create(), update(), get() return types changed
• PredefinedGetResponse union members renamed to UnionMember0-5

Zero Trust Tunnels

Response type removals:

All Cloudflared-specific response types have been removed.

// Before (v5)
import { 
  CloudflaredCreateResponse,
  CloudflaredListResponse,
  CloudflaredDeleteResponse,
  CloudflaredEditResponse,
  CloudflaredGetResponse,
  CloudflaredListResponsesV4PagePaginationArray
} from 'cloudflare';

// After (v6)
// All of these types have been removed

Changes:

• Removed all Cloudflared*Response types
• Removed: CloudflaredListResponsesV4PagePaginationArray

New features in v6

While v6 includes many breaking changes, it also introduces powerful new capabilities across the SDK.

New top-level resources

Abuse Reports

• Reports: create, list, get
• Mitigations: sub-resource for abuse mitigations

AI Search

• Instances: create, update, list, delete, read, stats
• Items: list, get
• Jobs: create, list, get, logs
• Tokens: create, update, list, delete, read

Connectivity

• Directory Services: create, update, list, delete, get
• Supports IPv4, IPv6, dual-stack, and hostname configurations

Organizations

• Organizations: create, update, list, delete, get
• OrganizationProfile: update, get
• Hierarchical organization support with parent/child relationships

R2 Data Catalog

• Catalog: list, enable, disable, get
• Credentials: create
• MaintenanceConfigs: update, get
• Namespaces: list
• Tables: list, maintenance config management
• Apache Iceberg integration

Realtime Kit

• Apps: get, post
• Meetings: create, get, participant management
• Livestreams: 10+ methods for streaming
• Recordings: start, pause, stop, get
• Sessions: transcripts, summaries, chat
• Webhooks: full CRUD
• ActiveSession: polls, kick participants
• Analytics: organization analytics

Token Validation

• Configuration: create, list, delete, edit, get
• Credentials: update
• Rules: create, list, delete, bulkCreate, bulkEdit, edit, get
• JWT validation with RS256/384/512, PS256/384/512, ES256, ES384

Enhanced existing resources

D1 Time Travel

Point-in-time recovery capabilities:

// Get bookmark for point-in-time recovery
const bookmark = await client.d1.database.timeTravel.getBookmark(dbId);

// Restore to a specific point in time
await client.d1.database.timeTravel.restore(dbId, {
  bookmark: 'bookmark-id',
});

Queues Subscriptions

Event subscriptions from multiple sources:

await client.queues.subscriptions.create(accountId, queueId, {
  event_source: {
    type: 'r2',
    bucket: 'my-bucket',
    // ...
  },
});

Supported event sources: Images, KV, R2, Vectorize, Workers AI, Workers Builds, Workflows

Workers Observability

New observability settings:

const script = await client.workers.scripts.get(scriptName);
console.log(script.observability); // logging configuration
console.log(script.startup_time_ms); // startup timing
console.log(script.references); // external dependencies

Zero Trust AI Controls / MCP

Model Context Protocol support:

// Portals
await client.zeroTrust.access.aiControls.mcp.portals.create({ /* ... */ });

// Servers
await client.zeroTrust.access.aiControls.mcp.servers.create({ /* ... */ });
await client.zeroTrust.access.aiControls.mcp.servers.sync(serverId);

Migration checklist

1. Audit your current usage

   Review which Cloudflare services your application uses and check the breaking changes for each.

2. Update dependencies

   npm install cloudflare@6.0.0-beta.1
   
3. Fix TypeScript errors

   Run TypeScript compilation to identify all breaking changes:

   npx tsc --noEmit
   
4. Update imports

   Replace any renamed types in your import statements.

5. Update method calls

   • Add required parameters where needed
   • Update pagination patterns
   • Migrate from deprecated methods (e.g., Pipelines v0 → v1)
6. Test thoroughly

   Run your test suite to ensure all functionality works as expected with the new types and behaviors.

7. Review new features

   Consider adopting new v6 features that could benefit your application.

Common patterns

Handling discriminated unions

Many response types are now discriminated unions for better type safety:

// DNS Records
const record = await client.dns.records.get(zoneId, recordId);

// TypeScript now knows the specific type based on the record type
if (record.type === 'A') {
  console.log(record.content); // string (IP address)
} else if (record.type === 'MX') {
  console.log(record.priority); // number
}

Updated pagination

Some resources have changed pagination types:

// Before (v5) - SinglePage
for await (const item of client.iam.resourceGroups.list()) {
  // ...
}

// After (v6) - Still works the same way
for await (const item of client.iam.resourceGroups.list()) {
  // ...
}

Required vs optional parameters

Many parameters have changed from optional to required. Always check the TypeScript types to see what’s required:

// TypeScript will error if you forget required parameters
await client.addressing.prefixes.bgp.create({
  account_id: 'abc123',
  cidr: '203.0.113.0/24', // Required in v6, was optional in v5
});

Getting help

If you encounter issues during migration:

1. Check the full CHANGELOG for detailed change information
2. Review the TypeScript SDK documentation
3. Open an issue on GitHub if you find bugs or have questions

Remember that v6.0.0-beta.1 is in Beta. Please report any issues you encounter to help improve the release.