fix: reduce global DOM/Node type conflicts in server-only packages (#12737)

AlessioGr · web-flow · commit 67fb29b2a4a1 · 2025-06-11T20:59:19.000Z
Currently, we globally enable both DOM and Node.js types. While this mostly works, it can cause conflicts - particularly with `fetch`. For example, TypeScript may incorrectly allow browser-only properties (like `cache`) and reject valid Node.js ones like `dispatcher`. This PR disables DOM types for server-only packages like payload, ensuring Node-specific typings are applied. This caught a few instances of incorrect fetch usage that were previously masked by overlapping DOM types. This is not a perfect solution - packages that contain both server and client code (like richtext-lexical or next) will still suffer from this issue. However, it's an improvement in cases where we can cleanly separate server and client types, like for the `payload` package which is server-only. ## Use-case This change enables #12622 to explore using node-native fetch + `dispatcher`, instead of `node-fetch` + `agent`. Currently, it will incorrectly report that `dispatcher` is not a valid property for node-native fetch
diff --git a/package.json b/package.json
@@ -141,7 +141,7 @@
     "@types/fs-extra": "^11.0.2",
     "@types/jest": "29.5.12",
     "@types/minimist": "1.2.5",
-    "@types/node": "22.5.4",
+    "@types/node": "22.15.30",
     "@types/react": "19.1.0",
     "@types/react-dom": "19.1.2",
     "@types/shelljs": "0.8.15",
diff --git a/packages/create-payload-app/package.json b/packages/create-payload-app/package.json
@@ -77,7 +77,7 @@
     "@types/esprima": "^4.0.6",
     "@types/fs-extra": "^9.0.12",
     "@types/jest": "29.5.12",
-    "@types/node": "22.5.4"
+    "@types/node": "22.15.30"
   },
   "engines": {
     "node": "^18.20.2 || >=20.9.0"
diff --git a/packages/create-payload-app/src/lib/examples.ts b/packages/create-payload-app/src/lib/examples.ts
@@ -7,7 +7,7 @@ export async function getExamples({ branch }: { branch: string }): Promise<Proje
 
   const response = await fetch(url)
 
-  const examplesResponseList: { name: string; path: string }[] = await response.json()
+  const examplesResponseList = (await response.json()) as { name: string; path: string }[]
 
   const examples: ProjectExample[] = examplesResponseList.map((example) => ({
     name: example.name,
diff --git a/packages/create-payload-app/src/utils/getLatestPackageVersion.ts b/packages/create-payload-app/src/utils/getLatestPackageVersion.ts
@@ -19,7 +19,7 @@ export async function getLatestPackageVersion({
 }) {
   try {
     const response = await fetch(`https://registry.npmjs.org/${packageName}`)
-    const data = await response.json()
+    const data = (await response.json()) as { 'dist-tags': { latest: string } }
     const latestVersion = data['dist-tags'].latest
 
     if (debug) {
diff --git a/packages/create-payload-app/tsconfig.json b/packages/create-payload-app/tsconfig.json
@@ -1,3 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/db-mongodb/tsconfig.json b/packages/db-mongodb/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }, { "path": "../translations" }]
+  "references": [{ "path": "../payload" }, { "path": "../translations" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/db-postgres/tsconfig.json b/packages/db-postgres/tsconfig.json
@@ -10,5 +10,9 @@
     {
       "path": "../drizzle"
     }
-  ]
+  ],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/db-sqlite/tsconfig.json b/packages/db-sqlite/tsconfig.json
@@ -10,5 +10,9 @@
     {
       "path": "../drizzle"
     }
-  ]
+  ],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/db-vercel-postgres/tsconfig.json b/packages/db-vercel-postgres/tsconfig.json
@@ -10,5 +10,9 @@
     {
       "path": "../drizzle"
     }
-  ]
+  ],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/drizzle/tsconfig.json b/packages/drizzle/tsconfig.json
@@ -4,6 +4,8 @@
     /* TODO: remove the following lines */
     "strict": false,
     "noUncheckedIndexedAccess": false,
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
   },
   "references": [{ "path": "../payload" }, { "path": "../translations" }]
 }
diff --git a/packages/email-nodemailer/tsconfig.json b/packages/email-nodemailer/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }]
+  "references": [{ "path": "../payload" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/email-resend/tsconfig.json b/packages/email-resend/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }]
+  "references": [{ "path": "../payload" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/graphql/tsconfig.json b/packages/graphql/tsconfig.json
@@ -4,6 +4,8 @@
     /* TODO: remove the following lines */
     "strict": false,
     "noUncheckedIndexedAccess": false,
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
   },
   "references": [{ "path": "../payload" }]
 }
diff --git a/packages/payload-cloud/tsconfig.json b/packages/payload-cloud/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }]
+  "references": [{ "path": "../payload" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/payload/src/fields/validations.ts b/packages/payload/src/fields/validations.ts
@@ -344,7 +344,10 @@ export const json: JSONFieldValidation = (
         }
         return response.json()
       })
-      .then((json) => {
+      .then((_json) => {
+        const json = _json as {
+          id: string
+        }
         const jsonSchemaSanitizations = {
           id: undefined,
           $id: json.id,
diff --git a/packages/payload/src/preferences/requestHandlers/delete.ts b/packages/payload/src/preferences/requestHandlers/delete.ts
@@ -20,6 +20,7 @@ export const deleteHandler: PayloadHandler = async (incomingReq): Promise<Respon
 
   if (data) {
     reqWithData.data = data
+    // @ts-expect-error
     reqWithData.json = () => Promise.resolve(data)
   }
 
diff --git a/packages/payload/src/preferences/requestHandlers/findOne.ts b/packages/payload/src/preferences/requestHandlers/findOne.ts
@@ -20,6 +20,7 @@ export const findByIDHandler: PayloadHandler = async (incomingReq): Promise<Resp
 
   if (data) {
     reqWithData.data = data
+    // @ts-expect-error
     reqWithData.json = () => Promise.resolve(data)
   }
 
diff --git a/packages/payload/src/preferences/requestHandlers/update.ts b/packages/payload/src/preferences/requestHandlers/update.ts
@@ -20,6 +20,7 @@ export const updateHandler: PayloadHandler = async (incomingReq) => {
 
   if (data) {
     reqWithData.data = data
+    // @ts-expect-error
     reqWithData.json = () => Promise.resolve(data)
   }
 
diff --git a/packages/payload/src/utilities/addDataAndFileToRequest.ts b/packages/payload/src/utilities/addDataAndFileToRequest.ts
@@ -24,6 +24,7 @@ export const addDataAndFileToRequest: AddDataAndFileToRequest = async (req) => {
         req.payload.logger.error(error)
       } finally {
         req.data = data
+        // @ts-expect-error
         req.json = () => Promise.resolve(data)
       }
     } else if (bodyByteSize && contentType?.includes('multipart/')) {
diff --git a/packages/payload/src/utilities/handleEndpoints.ts b/packages/payload/src/utilities/handleEndpoints.ts
@@ -92,6 +92,7 @@ export const handleEndpoints = async ({
       config: incomingConfig,
       path,
       request: new Request(url, {
+        // @ts-expect-error // TODO: check if this is required
         cache: request.cache,
         credentials: request.credentials,
         headers: request.headers,
diff --git a/packages/payload/src/utilities/routeError.ts b/packages/payload/src/utilities/routeError.ts
@@ -21,7 +21,7 @@ export const routeError = async ({
   config: Promise<SanitizedConfig> | SanitizedConfig
   err: APIError
   req: PayloadRequest | Request
-}) => {
+}): Promise<Response> => {
   if ('payloadInitError' in err && err.payloadInitError === true) {
     // do not attempt initializing Payload if the error is due to a failed initialization. Otherwise,
     // it will cause an infinite loop of initialization attempts and endless error responses, without
diff --git a/packages/payload/tsconfig.json b/packages/payload/tsconfig.json
@@ -1,4 +1,9 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../translations" }]
+  "references": [{ "path": "../translations" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as payload is a server-only package.
+    // This ensures node types do not conflict with node types (e.g. fetch.dispatcher)
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/plugin-cloud-storage/tsconfig.json b/packages/plugin-cloud-storage/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }, { "path": "../ui" }]
+  "references": [{ "path": "../payload" }, { "path": "../ui" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/plugin-redirects/tsconfig.json b/packages/plugin-redirects/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }]
+  "references": [{ "path": "../payload" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/plugin-sentry/tsconfig.json b/packages/plugin-sentry/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }]
+  "references": [{ "path": "../payload" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/richtext-lexical/package.json b/packages/richtext-lexical/package.json
@@ -396,7 +396,7 @@
     "@payloadcms/eslint-config": "workspace:*",
     "@types/escape-html": "1.0.4",
     "@types/json-schema": "7.0.15",
-    "@types/node": "22.5.4",
+    "@types/node": "22.15.30",
     "@types/react": "19.1.0",
     "@types/react-dom": "19.1.2",
     "babel-plugin-react-compiler": "19.1.0-rc.2",
diff --git a/packages/richtext-slate/package.json b/packages/richtext-slate/package.json
@@ -66,7 +66,7 @@
   "devDependencies": {
     "@payloadcms/eslint-config": "workspace:*",
     "@types/is-hotkey": "^0.1.10",
-    "@types/node": "22.5.4",
+    "@types/node": "22.15.30",
     "@types/react": "19.1.0",
     "@types/react-dom": "19.1.2",
     "payload": "workspace:*"
diff --git a/packages/storage-azure/src/client/AzureClientUploadHandler.ts b/packages/storage-azure/src/client/AzureClientUploadHandler.ts
@@ -13,7 +13,9 @@ export const AzureClientUploadHandler = createClientUploadHandler({
       method: 'POST',
     })
 
-    const { url } = await response.json()
+    const { url } = (await response.json()) as {
+      url: string
+    }
 
     await fetch(url, {
       body: file,
diff --git a/packages/storage-azure/src/generateSignedURL.ts b/packages/storage-azure/src/generateSignedURL.ts
@@ -28,7 +28,11 @@ export const getGenerateSignedURLHandler = ({
       throw new APIError('Unreachable')
     }
 
-    const { collectionSlug, filename, mimeType } = await req.json()
+    const { collectionSlug, filename, mimeType } = (await req.json()) as {
+      collectionSlug: string
+      filename: string
+      mimeType: string
+    }
 
     const collectionS3Config = collections[collectionSlug]
     if (!collectionS3Config) {
diff --git a/packages/storage-azure/tsconfig.json b/packages/storage-azure/tsconfig.json
@@ -5,9 +5,11 @@
     "noEmit": false /* Do not emit outputs. */,
     "emitDeclarationOnly": true,
     "outDir": "./dist" /* Specify an output folder for all emitted files. */,
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
     "rootDir": "./src" /* Specify the root folder within your source files. */,
   },
   "exclude": ["dist", "node_modules"],
   "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts", "src/**/*.json"],
-  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }]
+  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }],
 }
diff --git a/packages/storage-gcs/src/client/GcsClientUploadHandler.ts b/packages/storage-gcs/src/client/GcsClientUploadHandler.ts
@@ -13,7 +13,7 @@ export const GcsClientUploadHandler = createClientUploadHandler({
       method: 'POST',
     })
 
-    const { url } = await response.json()
+    const { url } = (await response.json()) as { url: string }
 
     await fetch(url, {
       body: file,
diff --git a/packages/storage-gcs/src/generateSignedURL.ts b/packages/storage-gcs/src/generateSignedURL.ts
@@ -28,7 +28,11 @@ export const getGenerateSignedURLHandler = ({
       throw new APIError('Unreachable')
     }
 
-    const { collectionSlug, filename, mimeType } = await req.json()
+    const { collectionSlug, filename, mimeType } = (await req.json()) as {
+      collectionSlug: string
+      filename: string
+      mimeType: string
+    }
 
     const collectionS3Config = collections[collectionSlug]
     if (!collectionS3Config) {
diff --git a/packages/storage-gcs/tsconfig.json b/packages/storage-gcs/tsconfig.json
@@ -6,6 +6,8 @@
     "emitDeclarationOnly": true,
     "outDir": "./dist" /* Specify an output folder for all emitted files. */,
     "rootDir": "./src" /* Specify the root folder within your source files. */,
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
   },
   "exclude": ["dist", "node_modules"],
   "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts", "src/**/*.json"],
diff --git a/packages/storage-s3/src/client/S3ClientUploadHandler.ts b/packages/storage-s3/src/client/S3ClientUploadHandler.ts
@@ -13,7 +13,9 @@ export const S3ClientUploadHandler = createClientUploadHandler({
       method: 'POST',
     })
 
-    const { url } = await response.json()
+    const { url } = (await response.json()) as {
+      url: string
+    }
 
     await fetch(url, {
       body: file,
diff --git a/packages/storage-s3/src/generateSignedURL.ts b/packages/storage-s3/src/generateSignedURL.ts
@@ -30,7 +30,11 @@ export const getGenerateSignedURLHandler = ({
       throw new APIError('Content-Type expected to be application/json', 400)
     }
 
-    const { collectionSlug, filename, mimeType } = await req.json()
+    const { collectionSlug, filename, mimeType } = (await req.json()) as {
+      collectionSlug: string
+      filename: string
+      mimeType: string
+    }
 
     const collectionS3Config = collections[collectionSlug]
     if (!collectionS3Config) {
diff --git a/packages/storage-s3/src/staticHandler.ts b/packages/storage-s3/src/staticHandler.ts
@@ -85,7 +85,7 @@ export const getHandler = ({
             command,
             typeof signedDownloads === 'object' ? signedDownloads : { expiresIn: 7200 },
           )
-          return Response.redirect(signedUrl)
+          return Response.redirect(signedUrl, 302)
         }
       }
 
diff --git a/packages/storage-s3/tsconfig.json b/packages/storage-s3/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }]
+  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/storage-uploadthing/tsconfig.json b/packages/storage-uploadthing/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }]
+  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/storage-vercel-blob/src/staticHandler.ts b/packages/storage-vercel-blob/src/staticHandler.ts
@@ -41,7 +41,10 @@ export const getStaticHandler = (
       }
 
       const response = await fetch(`${fileUrl}?${uploadedAtString}`, {
-        cache: 'no-store',
+        headers: {
+          'Cache-Control': 'no-store, no-cache, must-revalidate',
+          Pragma: 'no-cache',
+        },
       })
 
       const blob = await response.blob()
diff --git a/packages/storage-vercel-blob/tsconfig.json b/packages/storage-vercel-blob/tsconfig.json
@@ -1,4 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
-  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }]
+  "references": [{ "path": "../payload" }, { "path": "../plugin-cloud-storage" }],
+  "compilerOptions": {
+    // Do not include DOM and DOM.Iterable as this is a server-only package.
+    "lib": ["ES2022"],
+  }
 }
diff --git a/packages/translations/tsconfig.json b/packages/translations/tsconfig.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/tsconfig.base.json b/tsconfig.base.json

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"extends": "../../tsconfig.base.json",`
	`3`	`+ "compilerOptions": {`
	`4`	`+ // Do not include DOM and DOM.Iterable as this is a server-only package.`
	`5`	`+ "lib": ["ES2022"],`
	`6`	`+ }`
`3`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"extends": "../../tsconfig.base.json",`
`3`		`- "references": [{ "path": "../payload" }, { "path": "../translations" }]`
	`3`	`+ "references": [{ "path": "../payload" }, { "path": "../translations" }],`
	`4`	`+ "compilerOptions": {`
	`5`	`+ // Do not include DOM and DOM.Iterable as this is a server-only package.`
	`6`	`+ "lib": ["ES2022"],`
	`7`	`+ }`
`4`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -10,5 +10,9 @@`
`10`	`10`	`{`
`11`	`11`	`"path": "../drizzle"`
`12`	`12`	`}`
`13`		`- ]`
	`13`	`+ ],`
	`14`	`+ "compilerOptions": {`
	`15`	`+ // Do not include DOM and DOM.Iterable as this is a server-only package.`
	`16`	`+ "lib": ["ES2022"],`
	`17`	`+ }`
`14`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,8 @@`
`4`	`4`	`/* TODO: remove the following lines */`
`5`	`5`	`"strict": false,`
`6`	`6`	`"noUncheckedIndexedAccess": false,`
	`7`	`+ // Do not include DOM and DOM.Iterable as this is a server-only package.`
	`8`	`+ "lib": ["ES2022"],`
`7`	`9`	`},`
`8`	`10`	`"references": [{ "path": "../payload" }, { "path": "../translations" }]`
`9`	`11`	`}`