fix(storage-r2): build error due to types issue in R2 Bucket type (#15670)

Since we were hardcoding the types for some of the bucket options this has drifted from Cloudflare's own types causing a build error. Now the trick is that we have to hardcode some of the types since we need to keep them Node compatible, otherwise it would error locally and pass on Cloudflare due to Workers runtime. This PR addresses the following: - Reuses R2Range type (which is safe to do) - Keeps the rest of the types hardcoded - Adds a test to make sure that the type is correctly assignable to the R2Bucket type Closes https://github.com/payloadcms/payload/issues/15414 Tested deployment to CF using `3.77.0-internal.16f474b`
2026-02-18 18:46:49 +00:00
parent 6af3673020
commit 7d1e233167
9 changed files with 70 additions and 44 deletions
@@ -60,6 +60,7 @@
    "build:sdk": "turbo build --filter \"@payloadcms/sdk\"",
    "build:storage-azure": "turbo build --filter \"@payloadcms/storage-azure\"",
    "build:storage-gcs": "turbo build --filter \"@payloadcms/storage-gcs\"",
+    "build:storage-r2": "turbo build --filter \"@payloadcms/storage-r2\"",
    "build:storage-s3": "turbo build --filter \"@payloadcms/storage-s3\"",
    "build:storage-uploadthing": "turbo build --filter \"@payloadcms/storage-uploadthing\"",
    "build:storage-vercel-blob": "turbo build --filter \"@payloadcms/storage-vercel-blob\"",
@@ -50,6 +50,7 @@
    "@payloadcms/plugin-cloud-storage": "workspace:*"
  },
  "devDependencies": {
+    "@cloudflare/workers-types": "4.20260218.0",
    "payload": "workspace:*"
  },
  "peerDependencies": {
@@ -46,7 +46,7 @@ export const getHandler = ({ bucket, collection, prefix = '' }: Args): StaticHan
      // Get object with range if needed
      // Due to https://github.com/cloudflare/workers-sdk/issues/6047
      // We cannot send a Headers instance to Miniflare
-      const obj: R2ObjectBody =
+      const obj =
        rangeResult.type === 'partial' && !isMiniflare
          ? await bucket?.get(key, {
              range: {
@@ -56,7 +56,7 @@ export const getHandler = ({ bucket, collection, prefix = '' }: Args): StaticHan
            })
          : await bucket?.get(key)

-      if (obj?.body == undefined) {
+      if (!obj || obj.body == undefined) {
        return new Response(null, { status: 404, statusText: 'Not Found' })
      }

@@ -1,11 +1,11 @@
-export interface R2Range {
-  /** The number of bytes to return */
-  length?: number
-  /** The byte offset to start from (inclusive) */
-  offset?: number
-  /** Return the last n bytes */
-  suffix?: number
-}
+/**
+ * R2 API types compatible with both Node (Miniflare) and Cloudflare Workers.
+ * R2Range is sourced from Cloudflare so it cannot drift; other types are our own
+ * so Node's Blob/Buffer/Headers are accepted and we avoid strict Workers-only types.
+ */
+import type { R2Range } from '@cloudflare/workers-types/2023-07-01'
+
+export type { R2Range }

 export interface R2GetOptions {
  [key: string]: any
@@ -16,17 +16,9 @@ export interface R2GetOptions {
 export interface R2Bucket {
  createMultipartUpload(key: string, options?: any): Promise<R2MultipartUpload>
  delete(keys: string | string[]): Promise<void>
-  get(key: string, options?: R2GetOptions): Promise<any | null>
-  head(key: string): Promise<any>
+  get(key: string, options?: R2GetOptions): Promise<null | R2ObjectBody>
+  head(key: string): Promise<null | R2Object>
  list(options?: any): Promise<any>
-  put(
-    key: string,
-    value: ArrayBuffer | ArrayBufferView | Blob | null | ReadableStream | string,
-    options?: {
-      httpMetadata?: any | Headers
-      onlyIf: any
-    } & any,
-  ): Promise<any | null>
  put(
    key: string,
    value: ArrayBuffer | ArrayBufferView | Blob | null | ReadableStream | string,
@@ -49,9 +41,9 @@ export interface R2Object {
  readonly httpMetadata?: R2HTTPMetadata
  readonly key: string
  readonly size: number
-
  writeHttpMetadata(headers: Headers): void
 }
+
 export interface R2ObjectBody extends R2Object {
  get body(): ReadableStream
 }
@@ -68,6 +60,11 @@ export interface R2MultipartUpload {
  ): Promise<R2UploadedPart>
 }

+export interface R2UploadedPart {
+  etag: string
+  partNumber: number
+}
+
 export interface R2StorageClientUploadContext {
  key: string
 }
@@ -84,8 +81,3 @@ export type R2StorageMultipartUploadHandlerParams = {
  multipartKey?: string
  multipartNumber?: string
 }
-
-export interface R2UploadedPart {
-  etag: string
-  partNumber: number
-}
@@ -100,7 +100,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      escape-html:
        specifier: ^1.0.3
        version: 1.0.3
@@ -202,7 +202,7 @@ importers:
        version: 4.0.15(@opentelemetry/api@1.9.0)(@types/node@22.15.30)(jiti@2.6.1)(jsdom@28.0.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sass-embedded@1.97.3)(sass@1.97.3)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
      wrangler:
        specifier: ~4.61.1
-        version: 4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+        version: 4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6)

  packages/admin-bar:
    dependencies:
@@ -297,7 +297,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      prompts:
        specifier: 2.4.2
        version: 2.4.2
@@ -377,7 +377,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      pg:
        specifier: 8.16.3
        version: 8.16.3
@@ -423,7 +423,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      prompts:
        specifier: 2.4.2
        version: 2.4.2
@@ -466,7 +466,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      pg:
        specifier: 8.16.3
        version: 8.16.3
@@ -509,7 +509,7 @@ importers:
        version: 2.0.3
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      prompts:
        specifier: 2.4.2
        version: 2.4.2
@@ -1624,6 +1624,9 @@ importers:
        specifier: workspace:*
        version: link:../plugin-cloud-storage
    devDependencies:
+      '@cloudflare/workers-types':
+        specifier: 4.20260218.0
+        version: 4.20260218.0
      payload:
        specifier: workspace:*
        version: link:../payload
@@ -2194,7 +2197,7 @@ importers:
        version: 15.4.11(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.97.3)
      next-sitemap:
        specifier: ^4.2.3
-        version: 4.2.3(next@15.4.11(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.97.3))
+        version: 4.2.3(next@15.4.11(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.97.3))
      payload:
        specifier: workspace:*
        version: link:../../packages/payload
@@ -2296,6 +2299,9 @@ importers:
      '@azure/storage-blob':
        specifier: ^12.11.0
        version: 12.31.0
+      '@cloudflare/workers-types':
+        specifier: 4.20260218.0
+        version: 4.20260218.0
      '@date-fns/tz':
        specifier: 1.2.0
        version: 1.2.0
@@ -2313,7 +2319,7 @@ importers:
        version: 16.2.0-canary.29
      '@opennextjs/cloudflare':
        specifier: 1.16.1
-        version: 1.16.1(encoding@0.1.13)(next@16.2.0-canary.29(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-react-compiler@19.1.0-rc.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.77.4))(wrangler@4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6))
+        version: 1.16.1(encoding@0.1.13)(next@16.2.0-canary.29(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-react-compiler@19.1.0-rc.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.77.4))(wrangler@4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6))
      '@payloadcms/admin-bar':
        specifier: workspace:*
        version: link:../packages/admin-bar
@@ -2481,7 +2487,7 @@ importers:
        version: 0.31.7
      drizzle-orm:
        specifier: 0.44.7
-        version: 0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
+        version: 0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3)
      escape-html:
        specifier: 1.0.3
        version: 1.0.3
@@ -2556,7 +2562,7 @@ importers:
        version: 4.0.15(@opentelemetry/api@1.9.0)(@types/node@22.19.9)(jiti@2.6.1)(jsdom@28.0.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sass-embedded@1.97.3)(sass@1.77.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
      wrangler:
        specifier: ~4.61.1
-        version: 4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+        version: 4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6)
      zod:
        specifier: ^3.25.5
        version: 3.25.76
@@ -3789,6 +3795,9 @@ packages:
    cpu: [x64]
    os: [win32]

+  '@cloudflare/workers-types@4.20260218.0':
+    resolution: {integrity: sha512-E28uJNJb9J9pca3RaxjXm1JxAjp8td9/cudkY+IT8rio71NlshN7NKMe2Cr/6GN+RufbSnp+N3ZKP74xgUaL0A==}
+
  '@corex/deepmerge@4.0.43':
    resolution: {integrity: sha512-N8uEMrMPL0cu/bdboEWpQYb/0i2K5Qn8eCsxzOmxSggJbbQte7ljMRoXm917AbntqTGOzdTu+vP3KOOzoC70HQ==}

@@ -16585,6 +16594,8 @@ snapshots:
  '@cloudflare/workerd-windows-64@1.20260128.0':
    optional: true

+  '@cloudflare/workers-types@4.20260218.0': {}
+
  '@corex/deepmerge@4.0.43': {}

  '@cspotcode/source-map-support@0.8.1':
@@ -18181,7 +18192,7 @@ snapshots:
      - aws-crt
      - supports-color

-  '@opennextjs/cloudflare@1.16.1(encoding@0.1.13)(next@16.2.0-canary.29(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-react-compiler@19.1.0-rc.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.77.4))(wrangler@4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6))':
+  '@opennextjs/cloudflare@1.16.1(encoding@0.1.13)(next@16.2.0-canary.29(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-react-compiler@19.1.0-rc.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.77.4))(wrangler@4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6))':
    dependencies:
      '@ast-grep/napi': 0.40.0
      '@dotenvx/dotenvx': 1.31.0
@@ -18191,7 +18202,7 @@ snapshots:
      glob: 12.0.0
      next: 16.2.0-canary.29(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-react-compiler@19.1.0-rc.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.77.4)
      ts-tqdm: 0.8.6
-      wrangler: 4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6)
+      wrangler: 4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6)
      yargs: 18.0.0
    transitivePeerDependencies:
      - aws-crt
@@ -22256,8 +22267,9 @@ snapshots:
    transitivePeerDependencies:
      - supports-color

-  drizzle-orm@0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3):
+  drizzle-orm@0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.10.2)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3):
    optionalDependencies:
+      '@cloudflare/workers-types': 4.20260218.0
      '@libsql/client': 0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
      '@opentelemetry/api': 1.9.0
      '@types/better-sqlite3': 7.6.13
@@ -22266,8 +22278,9 @@ snapshots:
      better-sqlite3: 11.10.0
      pg: 8.16.3

-  drizzle-orm@0.44.7(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3):
+  drizzle-orm@0.44.7(@cloudflare/workers-types@4.20260218.0)(@libsql/client@0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.11.6)(@vercel/postgres@0.9.0)(better-sqlite3@11.10.0)(pg@8.16.3):
    optionalDependencies:
+      '@cloudflare/workers-types': 4.20260218.0
      '@libsql/client': 0.14.0(bufferutil@4.1.0)(utf-8-validate@6.0.6)
      '@opentelemetry/api': 1.9.0
      '@types/better-sqlite3': 7.6.13
@@ -25074,7 +25087,7 @@ snapshots:
    transitivePeerDependencies:
      - supports-color

-  next-sitemap@4.2.3(next@15.4.11(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.97.3)):
+  next-sitemap@4.2.3(next@15.4.11(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.97.3)):
    dependencies:
      '@corex/deepmerge': 4.0.43
      '@next/env': 13.5.11
@@ -28047,7 +28060,7 @@ snapshots:
      '@cloudflare/workerd-linux-arm64': 1.20260128.0
      '@cloudflare/workerd-windows-64': 1.20260128.0

-  wrangler@4.61.1(bufferutil@4.1.0)(utf-8-validate@6.0.6):
+  wrangler@4.61.1(@cloudflare/workers-types@4.20260218.0)(bufferutil@4.1.0)(utf-8-validate@6.0.6):
    dependencies:
      '@cloudflare/kv-asset-handler': 0.4.2
      '@cloudflare/unenv-preset': 2.12.0(unenv@2.0.0-rc.24)(workerd@1.20260128.0)
@@ -28058,6 +28071,7 @@ snapshots:
      unenv: 2.0.0-rc.24
      workerd: 1.20260128.0
    optionalDependencies:
+      '@cloudflare/workers-types': 4.20260218.0
      fsevents: 2.3.3
    transitivePeerDependencies:
      - bufferutil
@@ -27,6 +27,7 @@
  "devDependencies": {
    "@aws-sdk/client-s3": "^3.614.0",
    "@azure/storage-blob": "^12.11.0",
+    "@cloudflare/workers-types": "4.20260218.0",
    "@date-fns/tz": "1.2.0",
    "@miniflare/d1": "2.14.4",
    "@miniflare/shared": "2.14.4",
@@ -0,0 +1,13 @@
+import type { R2StorageOptions } from '@payloadcms/storage-r2'
+
+/// <reference types="@cloudflare/workers-types/2023-07-01" />
+import { describe, expect, test } from 'tstyche'
+
+type PayloadR2Bucket = R2StorageOptions['bucket']
+
+describe('R2 type compatibility', () => {
+  test('Cloudflare R2Bucket is assignable to our R2Bucket', () => {
+    // R2Bucket here is the ambient global from @cloudflare/workers-types
+    expect<R2Bucket>().type.toBeAssignableTo<PayloadR2Bucket>()
+  })
+})
@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["r2-types.spec.ts"]
+}
@@ -1,3 +1,3 @@
 {
-  "testFileMatch": ["test/**/types.spec.ts"]
+  "testFileMatch": ["test/**/types.spec.ts", "test/**/r2-types.spec.ts"]
 }