feat: add ability to disable cache tags for admin thumbnails (#10319)

This PR adds `cacheTags: boolean` (default `true`) to allow users to
disable the appended document updatedAt value in the case of hosting
with third party CDNs which may not allow additional search params and
throw an error.

It also fixes how we append this value to consider the case where the
URL already contains parameters and appends it with `&` instead.

In the future `cacheTags` can be made an object to allow granularity for
disabling `eTag` headers used for caching as well.

The cache tag control should help with these two issues:
- Fixes #9880
- Fixes #9993

The appending of the value correctly addresses this:
- Fixes #10139

Author: paulpopus

.gitignore

@@ -317,3 +317,4 @@ test/databaseAdapter.js
 /filename-compound-index
 /media-with-relation-preview
 /media-without-relation-preview
+/media-without-cache-tags

docs/upload/overview.mdx

@@ -92,6 +92,7 @@ _An asterisk denotes that an option is required._
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`adminThumbnail`**           | Set the way that the [Admin Panel](../admin/overview) will display thumbnails for this Collection. [More](#admin-thumbnails)                                                                                                          |
 | **`bulkUpload`**               | Allow users to upload in bulk from the list view, default is true                                                                                                                                                                     |
+| **`cacheTags`**                | Set to `false` to disable the cache tag set in the UI for the admin thumbnail component. Useful for when CDNs don't allow certain cache queries.                                                                               |
 | **`crop`**                     | Set to `false` to disable the cropping tool in the [Admin Panel](../admin/overview). Crop is enabled by default. [More](#crop-and-focal-point-selector)                                                                               |
 | **`disableLocalStorage`**      | Completely disable uploading files to disk locally. [More](#disabling-local-upload-storage)                                                                                                                                           |
 | **`displayPreview`**           | Enable displaying preview of the uploaded file in Upload fields related to this Collection. Can be locally overridden by `displayPreview` option in Upload field. [More](/docs/fields/upload#config-options).                         |

packages/payload/src/collections/config/sanitize.ts

@@ -152,6 +152,7 @@ export const sanitizeCollection = async (
     // sanitize fields for reserved names
     sanitizeUploadFields(sanitized.fields, sanitized)
 
+    sanitized.upload.cacheTags = sanitized.upload?.cacheTags ?? true
     sanitized.upload.bulkUpload = sanitized.upload?.bulkUpload ?? true
     sanitized.upload.staticDir = sanitized.upload.staticDir || sanitized.slug
     sanitized.admin.useAsTitle =

packages/payload/src/uploads/types.ts

@@ -100,6 +100,12 @@ export type UploadConfig = {
    * @default true
    */
   bulkUpload?: boolean
+  /**
+   * Appends a cache tag to the image URL when fetching the thumbnail in the admin panel. It may be desirable to disable this when hosting via CDNs with strict parameters.
+   *
+   * @default true
+   */
+  cacheTags?: boolean
   /**
    * Enables cropping of images.
    * @default true

packages/ui/src/elements/Thumbnail/index.tsx

@@ -8,7 +8,6 @@ const baseClass = 'thumbnail'
 import type { SanitizedCollectionConfig } from 'payload'
 
 import { File } from '../../graphics/File/index.js'
-import { useIntersect } from '../../hooks/useIntersect.js'
 import { ShimmerEffect } from '../ShimmerEffect/index.js'
 
 export type ThumbnailProps = {
@@ -43,15 +42,21 @@ export const Thumbnail: React.FC<ThumbnailProps> = (props) => {
     }
   }, [fileSrc])
 
+  let src: string = ''
+
+  /**
+   * If an imageCacheTag is provided, append it to the fileSrc
+   * Check if the fileSrc already has a query string, if it does, append the imageCacheTag with an ampersand
+   */
+  if (fileSrc) {
+    const queryChar = fileSrc?.includes('?') ? '&' : '?'
+    src = imageCacheTag ? `${fileSrc}${queryChar}${imageCacheTag}` : fileSrc
+  }
+
   return (
     <div className={classNames}>
       {fileExists === undefined && <ShimmerEffect height="100%" />}
-      {fileExists && (
-        <img
-          alt={filename as string}
-          src={`${fileSrc}${imageCacheTag ? `?${imageCacheTag}` : ''}`}
-        />
-      )}
+      {fileExists && <img alt={filename as string} src={src} />}
       {fileExists === false && <File />}
     </div>
   )
@@ -87,12 +92,17 @@ export function ThumbnailComponent(props: ThumbnailComponentProps) {
     }
   }, [fileSrc])
 
+  /**
+   * If an imageCacheTag is provided, append it to the fileSrc
+   * Check if the fileSrc already has a query string, if it does, append the imageCacheTag with an ampersand
+   */
+  const queryChar = fileSrc.includes('?') ? '&' : '?'
+  const src = imageCacheTag ? `${fileSrc}${queryChar}${imageCacheTag}` : fileSrc
+
   return (
     <div className={classNames}>
       {fileExists === undefined && <ShimmerEffect height="100%" />}
-      {fileExists && (
-        <img alt={alt || filename} src={`${fileSrc}${imageCacheTag ? `?${imageCacheTag}` : ''}`} />
-      )}
+      {fileExists && <img alt={alt || filename} src={src} />}
       {fileExists === false && <File />}
     </div>
   )

packages/ui/src/elements/Upload/index.tsx

@@ -237,7 +237,7 @@ export const Upload: React.FC<UploadProps> = (props) => {
           enableAdjustments={showCrop || showFocalPoint}
           handleRemove={canRemoveUpload ? handleFileRemoval : undefined}
           hasImageSizes={hasImageSizes}
-          imageCacheTag={savedDocumentData.updatedAt}
+          imageCacheTag={uploadConfig?.cacheTags && savedDocumentData.updatedAt}
           uploadConfig={uploadConfig}
         />
       )}

test/uploads/collections/AdminThumbnailWithSearchQueries/index.ts

@@ -0,0 +1,27 @@
+import type { CollectionConfig } from 'payload'
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import { adminThumbnailWithSearchQueries } from '../../shared.js'
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+export const AdminThumbnailWithSearchQueries: CollectionConfig = {
+  slug: adminThumbnailWithSearchQueries,
+  hooks: {
+    afterRead: [
+      ({ doc }) => {
+        return {
+          ...doc,
+          // Test that URLs with additional queries are handled correctly
+          thumbnailURL: `/_next/image?url=${doc.url}&w=384&q=5`,
+        }
+      },
+    ],
+  },
+  upload: {
+    staticDir: path.resolve(dirname, 'test/uploads/media'),
+  },
+  fields: [],
+}

test/uploads/config.ts

@@ -7,6 +7,7 @@ import { devUser } from '../credentials.js'
 import removeFiles from '../helpers/removeFiles.js'
 import { AdminThumbnailFunction } from './collections/AdminThumbnailFunction/index.js'
 import { AdminThumbnailSize } from './collections/AdminThumbnailSize/index.js'
+import { AdminThumbnailWithSearchQueries } from './collections/AdminThumbnailWithSearchQueries/index.js'
 import { CustomUploadFieldCollection } from './collections/CustomUploadField/index.js'
 import { Uploads1 } from './collections/Upload1/index.js'
 import { Uploads2 } from './collections/Upload2/index.js'
@@ -17,6 +18,7 @@ import {
   enlargeSlug,
   focalNoSizesSlug,
   mediaSlug,
+  mediaWithoutCacheTagsSlug,
   mediaWithoutRelationPreviewSlug,
   mediaWithRelationPreviewSlug,
   reduceSlug,
@@ -582,6 +584,7 @@ export default buildConfigWithDefaults({
     Uploads1,
     Uploads2,
     AdminThumbnailFunction,
+    AdminThumbnailWithSearchQueries,
     AdminThumbnailSize,
     {
       slug: 'optional-file',
@@ -628,6 +631,18 @@ export default buildConfigWithDefaults({
         displayPreview: true,
       },
     },
+    {
+      slug: mediaWithoutCacheTagsSlug,
+      fields: [
+        {
+          name: 'title',
+          type: 'text',
+        },
+      ],
+      upload: {
+        cacheTags: false,
+      },
+    },
     {
       slug: mediaWithoutRelationPreviewSlug,
       fields: [
@@ -799,13 +814,31 @@ export default buildConfigWithDefaults({
       },
     })
 
+    await payload.create({
+      collection: AdminThumbnailWithSearchQueries.slug,
+      data: {},
+      file: {
+        ...imageFile,
+        name: `searchQueries-image-${imageFile.name}`,
+      },
+    })
+
     // Create media with and without relation preview
     const { id: uploadedImageWithPreview } = await payload.create({
       collection: mediaWithRelationPreviewSlug,
       data: {},
       file: imageFile,
     })
 
+    await payload.create({
+      collection: mediaWithoutCacheTagsSlug,
+      data: {},
+      file: {
+        ...imageFile,
+        name: `withoutCacheTags-image-${imageFile.name}`,
+      },
+    })
+
     const { id: uploadedImageWithoutPreview } = await payload.create({
       collection: mediaWithoutRelationPreviewSlug,
       data: {},

test/uploads/e2e.spec.ts

@@ -22,6 +22,8 @@ import { RESTClient } from '../helpers/rest.js'
 import { TEST_TIMEOUT_LONG } from '../playwright.config.js'
 import {
   adminThumbnailFunctionSlug,
+  adminThumbnailWithSearchQueries,
+  mediaWithoutCacheTagsSlug,
   adminThumbnailSizeSlug,
   animatedTypeMedia,
   audioSlug,
@@ -48,6 +50,8 @@ let audioURL: AdminUrlUtil
 let relationURL: AdminUrlUtil
 let adminThumbnailSizeURL: AdminUrlUtil
 let adminThumbnailFunctionURL: AdminUrlUtil
+let adminThumbnailWithSearchQueriesURL: AdminUrlUtil
+let mediaWithoutCacheTagsSlugURL: AdminUrlUtil
 let focalOnlyURL: AdminUrlUtil
 let withMetadataURL: AdminUrlUtil
 let withoutMetadataURL: AdminUrlUtil
@@ -68,6 +72,11 @@ describe('Uploads', () => {
     relationURL = new AdminUrlUtil(serverURL, relationSlug)
     adminThumbnailSizeURL = new AdminUrlUtil(serverURL, adminThumbnailSizeSlug)
     adminThumbnailFunctionURL = new AdminUrlUtil(serverURL, adminThumbnailFunctionSlug)
+    adminThumbnailWithSearchQueriesURL = new AdminUrlUtil(
+      serverURL,
+      adminThumbnailWithSearchQueries,
+    )
+    mediaWithoutCacheTagsSlugURL = new AdminUrlUtil(serverURL, mediaWithoutCacheTagsSlug)
     focalOnlyURL = new AdminUrlUtil(serverURL, focalOnlySlug)
     withMetadataURL = new AdminUrlUtil(serverURL, withMetadataSlug)
     withoutMetadataURL = new AdminUrlUtil(serverURL, withoutMetadataSlug)
@@ -430,6 +439,77 @@ describe('Uploads', () => {
     )
   })
 
+  test('should render adminThumbnail when using a custom thumbnail URL with additional queries', async () => {
+    await page.goto(adminThumbnailWithSearchQueriesURL.list)
+    await page.waitForURL(adminThumbnailWithSearchQueriesURL.list)
+
+    const genericUploadImage = page.locator('tr.row-1 .thumbnail img')
+    // Match the URL with the regex pattern
+    const regexPattern = /\/_next\/image\?url=.*?&w=384&q=5/
+
+    await expect(genericUploadImage).toHaveAttribute('src', regexPattern)
+  })
+
+  test('should render adminThumbnail without the additional cache tag', async () => {
+    const imageDoc = (
+      await payload.find({
+        collection: mediaWithoutCacheTagsSlug,
+        depth: 0,
+        pagination: false,
+        where: {
+          mimeType: {
+            equals: 'image/png',
+          },
+        },
+      })
+    ).docs[0]
+
+    await page.goto(mediaWithoutCacheTagsSlugURL.edit(imageDoc.id))
+
+    const genericUploadImage = page.locator('.file-details .thumbnail img')
+
+    const src = await genericUploadImage.getAttribute('src')
+
+    /**
+     * Regex matcher for date cache tags.
+     *
+     * @example it will match `?2022-01-01T00:00:00.000Z`
+     */
+    const cacheTagPattern = /\?\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/
+
+    expect(src).not.toMatch(cacheTagPattern)
+  })
+
+  test('should render adminThumbnail with the cache tag by default', async () => {
+    const imageDoc = (
+      await payload.find({
+        collection: adminThumbnailFunctionSlug,
+        depth: 0,
+        pagination: false,
+        where: {
+          mimeType: {
+            equals: 'image/png',
+          },
+        },
+      })
+    ).docs[0]
+
+    await page.goto(adminThumbnailFunctionURL.edit(imageDoc.id))
+
+    const genericUploadImage = page.locator('.file-details .thumbnail img')
+
+    const src = await genericUploadImage.getAttribute('src')
+
+    /**
+     * Regex matcher for date cache tags.
+     *
+     * @example it will match `?2022-01-01T00:00:00.000Z`
+     */
+    const cacheTagPattern = /\?\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/
+
+    expect(src).toMatch(cacheTagPattern)
+  })
+
   test('should render adminThumbnail when using a specific size', async () => {
     await page.goto(adminThumbnailSizeURL.list)
     await page.waitForURL(adminThumbnailSizeURL.list)