fix(storage-*): allow prefix to always exist as a field via alwaysInsertFields flag (#14949)

This PR adds a new top-level flag `alwaysInsertFields` in the storage
adapter plugin options to ensure the prefix field is always present in
the schema.

Some configurations have prefix dynamically set by environment, but this
can cause schema/db drift and issues where db migrations are needed, as
well as generated types being different between environments.

Now you can add `alwaysInsertFields: true` at the plugin level so that
the prefix field is always present regardless of what you set in
`prefix`, even when the plugin is disabled:
```
s3Storage({
  alwaysInsertFields: true, // prefix field will always exist in schema
  collections: {
    'media': true,
    'media-with-prefix': {
      prefix: process.env.MEDIA_PREFIX, // can be undefined without causing schema drift
    },
  },
  enabled: process.env.USE_S3 === 'true', // works even when disabled
  // ...
})
```

This is particularly useful for:
- Multi-tenant setups where prefix is set dynamically
- Environments where cloud storage is conditionally enabled (e.g., local
dev vs production)
- Ensuring consistent database schema across all environments

**This will be enabled by default and removed as a flag in Payload v4.**

Author: paulpopus

.gitignore

@@ -344,6 +344,8 @@ test/google-cloud-storage
 test/azurestoragedata/
 /media-without-delete-access
 /media-documents
+/media-with-always-insert-fields
+
 
 
 licenses.csv

docs/upload/storage-adapters.mdx

@@ -368,10 +368,11 @@ export default buildConfig({
 
 This plugin is configurable to work across many different Payload collections. A `*` denotes that the property is required.
 
-| Option           | Type                                | Description                                                                                                                       |
-| ---------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `collections` \* | `Record<string, CollectionOptions>` | Object with keys set to the slug of collections you want to enable the plugin for, and values set to collection-specific options. |
-| `enabled`        | `boolean`                           | To conditionally enable/disable plugin. Default: `true`.                                                                          |
+| Option               | Type                                | Description                                                                                                                                                                                                   |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `alwaysInsertFields` | `boolean`                           | When enabled, fields (like the prefix field) will always be inserted into the collection schema regardless of whether the plugin is enabled. This will be enabled by default in Payload v4. Default: `false`. |
+| `collections` \*     | `Record<string, CollectionOptions>` | Object with keys set to the slug of collections you want to enable the plugin for, and values set to collection-specific options.                                                                             |
+| `enabled`            | `boolean`                           | To conditionally enable/disable plugin. Default: `true`.                                                                                                                                                      |
 
 ## Collection-specific options
 
@@ -380,8 +381,8 @@ This plugin is configurable to work across many different Payload collections. A
 | `adapter` \*                  | [Adapter](https://github.com/payloadcms/payload/blob/main/packages/plugin-cloud-storage/src/types.ts#L49)         | Pass in the adapter that you'd like to use for this collection. You can also set this field to `null` for local development if you'd like to bypass cloud storage in certain scenarios and use local storage. |
 | `disableLocalStorage`         | `boolean`                                                                                                         | Choose to disable local storage on this collection. Defaults to `true`.                                                                                                                                       |
 | `disablePayloadAccessControl` | `true`                                                                                                            | Set to `true` to disable Payload's Access Control. [More](#payload-access-control)                                                                                                                            |
-| `prefix`                      | `string`                                                                                                          | Set to `media/images` to upload files inside `media/images` folder in the bucket.                                                                                                                             |
 | `generateFileURL`             | [GenerateFileURL](https://github.com/payloadcms/payload/blob/main/packages/plugin-cloud-storage/src/types.ts#L67) | Override the generated file URL with one that you create.                                                                                                                                                     |
+| `prefix`                      | `string`                                                                                                          | Set to `media/images` to upload files inside `media/images` folder in the bucket.                                                                                                                             |
 
 ## Payload Access Control
 

packages/plugin-cloud-storage/src/admin/fields/getFields.ts

@@ -3,11 +3,15 @@ import type { CollectionConfig, Field, GroupField, TextField } from 'payload'
 import path from 'path'
 
 interface Args {
+  /**
+   * When true, always insert the prefix field regardless of whether a prefix is configured.
+   */
+  alwaysInsertFields?: boolean
   collection: CollectionConfig
   prefix?: string
 }
 
-export const getFields = ({ collection, prefix }: Args): Field[] => {
+export const getFields = ({ alwaysInsertFields, collection, prefix }: Args): Field[] => {
   const baseURLField: TextField = {
     name: 'url',
     type: 'text',
@@ -99,8 +103,8 @@ export const getFields = ({ collection, prefix }: Args): Field[] => {
     fields.push(sizesField)
   }
 
-  // If prefix is enabled, save it to db
-  if (typeof prefix !== 'undefined') {
+  // If prefix is enabled or alwaysInsertFields is true, save it to db
+  if (typeof prefix !== 'undefined' || alwaysInsertFields) {
     let existingPrefixFieldIndex = -1
 
     const existingPrefixField = fields.find((existingField, i) => {
@@ -118,7 +122,7 @@ export const getFields = ({ collection, prefix }: Args): Field[] => {
     fields.push({
       ...basePrefixField,
       ...(existingPrefixField || {}),
-      defaultValue: path.posix.join(prefix),
+      defaultValue: prefix ? path.posix.join(prefix) : '',
     } as TextField)
   }
 

packages/plugin-cloud-storage/src/admin/index.ts

@@ -10,11 +10,11 @@ import { getFields } from './fields/getFields.js'
 export const cloudStorage =
   (pluginOptions: PluginOptions) =>
   (incomingConfig: Config): Config => {
-    const { collections: allCollectionOptions, enabled } = pluginOptions
+    const { alwaysInsertFields, collections: allCollectionOptions, enabled } = pluginOptions
     const config = { ...incomingConfig }
 
-    // Return early if disabled. Only webpack config mods are applied.
-    if (enabled === false) {
+    // If disabled and alwaysInsertFields is not true, skip processing
+    if (enabled === false && !alwaysInsertFields) {
       return config
     }
 
@@ -23,8 +23,10 @@ export const cloudStorage =
       collections: (config.collections || []).map((existingCollection) => {
         const options = allCollectionOptions[existingCollection.slug]
 
-        if (options?.adapter) {
+        // Process if adapter exists OR if alwaysInsertFields is true and this collection is configured
+        if (options?.adapter || (alwaysInsertFields && options)) {
           const fields = getFields({
+            alwaysInsertFields,
             collection: existingCollection,
             prefix: options.prefix,
           })

packages/plugin-cloud-storage/src/fields/getFields.ts

@@ -7,7 +7,11 @@ import type { GeneratedAdapter, GenerateFileURL } from '../types.js'
 import { getAfterReadHook } from '../hooks/afterRead.js'
 
 interface Args {
-  adapter: GeneratedAdapter
+  adapter?: GeneratedAdapter
+  /**
+   * When true, always insert the prefix field regardless of whether a prefix is configured.
+   */
+  alwaysInsertFields?: boolean
   collection: CollectionConfig
   disablePayloadAccessControl?: true
   generateFileURL?: GenerateFileURL
@@ -16,6 +20,7 @@ interface Args {
 
 export const getFields = ({
   adapter,
+  alwaysInsertFields,
   collection,
   disablePayloadAccessControl,
   generateFileURL,
@@ -40,7 +45,7 @@ export const getFields = ({
     },
   }
 
-  const fields = [...collection.fields, ...(adapter.fields || [])]
+  const fields = [...collection.fields, ...(adapter?.fields || [])]
 
   // Inject a hook into all URL fields to generate URLs
 
@@ -58,16 +63,24 @@ export const getFields = ({
     fields.splice(existingURLFieldIndex, 1)
   }
 
-  fields.push({
-    ...baseURLField,
-    ...(existingURLField || {}),
-    hooks: {
-      afterRead: [
-        getAfterReadHook({ adapter, collection, disablePayloadAccessControl, generateFileURL }),
-        ...(existingURLField?.hooks?.afterRead || []),
-      ],
-    },
-  } as TextField)
+  // Only add afterRead hook if adapter is provided
+  if (adapter) {
+    fields.push({
+      ...baseURLField,
+      ...(existingURLField || {}),
+      hooks: {
+        afterRead: [
+          getAfterReadHook({ adapter, collection, disablePayloadAccessControl, generateFileURL }),
+          ...(existingURLField?.hooks?.afterRead || []),
+        ],
+      },
+    } as TextField)
+  } else {
+    fields.push({
+      ...baseURLField,
+      ...(existingURLField || {}),
+    } as TextField)
+  }
 
   if (typeof collection.upload === 'object' && collection.upload.imageSizes) {
     let existingSizesFieldIndex = -1
@@ -99,15 +112,11 @@ export const getFields = ({
 
         const existingSizeURLField = existingSizeField?.fields.find(
           (existingField) => 'name' in existingField && existingField.name === 'url',
-        ) as GroupField
+        ) as TextField
 
-        return {
-          ...existingSizeField,
-          name: size.name,
-          type: 'group',
-          fields: [
-            ...(adapter.fields || []),
-            {
+        // Only add afterRead hook if adapter is provided
+        const sizeURLField: TextField = adapter
+          ? ({
               ...(existingSizeURLField || {}),
               ...baseURLField,
               hooks: {
@@ -125,17 +134,26 @@ export const getFields = ({
                     []),
                 ],
               },
-            },
-          ],
+            } as TextField)
+          : ({
+              ...(existingSizeURLField || {}),
+              ...baseURLField,
+            } as TextField)
+
+        return {
+          ...existingSizeField,
+          name: size.name,
+          type: 'group',
+          fields: [...(adapter?.fields || []), sizeURLField],
         } as Field
       }),
     }
 
     fields.push(sizesField)
   }
 
-  // If prefix is enabled, save it to db
-  if (typeof prefix !== 'undefined') {
+  // If prefix is enabled or alwaysInsertFields is true, save it to db
+  if (typeof prefix !== 'undefined' || alwaysInsertFields) {
     let existingPrefixFieldIndex = -1
 
     const existingPrefixField = fields.find((existingField, i) => {
@@ -153,7 +171,7 @@ export const getFields = ({
     fields.push({
       ...basePrefixField,
       ...(existingPrefixField || {}),
-      defaultValue: path.posix.join(prefix),
+      defaultValue: prefix ? path.posix.join(prefix) : '',
     } as TextField)
   }
 

packages/plugin-cloud-storage/src/plugin.ts

@@ -18,11 +18,46 @@ import { getAfterDeleteHook } from './hooks/afterDelete.js'
 export const cloudStoragePlugin =
   (pluginOptions: PluginOptions) =>
   (incomingConfig: Config): Config => {
-    const { collections: allCollectionOptions, enabled } = pluginOptions
+    const { alwaysInsertFields, collections: allCollectionOptions, enabled } = pluginOptions
     const config = { ...incomingConfig }
 
-    // Return early if disabled. Only webpack config mods are applied.
+    // If disabled but alwaysInsertFields is true, only insert fields without full plugin functionality
     if (enabled === false) {
+      if (alwaysInsertFields) {
+        return {
+          ...config,
+          collections: (config.collections || []).map((existingCollection) => {
+            const options = allCollectionOptions[existingCollection.slug]
+
+            if (options) {
+              // If adapter is provided, use it to get fields
+              const adapter = options.adapter
+                ? options.adapter({
+                    collection: existingCollection,
+                    prefix: options.prefix,
+                  })
+                : undefined
+
+              const fields = getFields({
+                adapter,
+                alwaysInsertFields: true,
+                collection: existingCollection,
+                disablePayloadAccessControl: options.disablePayloadAccessControl,
+                generateFileURL: options.generateFileURL,
+                prefix: options.prefix,
+              })
+
+              return {
+                ...existingCollection,
+                fields,
+              }
+            }
+
+            return existingCollection
+          }),
+        }
+      }
+
       return config
     }
 

packages/plugin-cloud-storage/src/types.ts

@@ -106,6 +106,16 @@ export interface CollectionOptions {
 }
 
 export interface PluginOptions {
+  /**
+   * When enabled, fields (like the prefix field) will always be inserted into
+   * the collection schema regardless of whether the plugin is enabled. This
+   * ensures a consistent schema across all environments.
+   *
+   * This will be enabled by default in Payload v4.
+   *
+   * @default false
+   */
+  alwaysInsertFields?: boolean
   collections: Partial<Record<UploadCollectionSlug, CollectionOptions>>
   /**
    * Whether or not to enable the plugin

packages/storage-azure/src/index.ts

@@ -26,6 +26,17 @@ export type AzureStorageOptions = {
    */
   allowContainerCreate: boolean
 
+  /**
+   * When enabled, fields (like the prefix field) will always be inserted into
+   * the collection schema regardless of whether the plugin is enabled. This
+   * ensures a consistent schema across all environments.
+   *
+   * This will be enabled by default in Payload v4.
+   *
+   * @default false
+   */
+  alwaysInsertFields?: boolean
+
   /**
    * Base URL for the Azure Blob storage account
    */
@@ -136,6 +147,7 @@ export const azureStorage: AzureStoragePlugin =
     }
 
     return cloudStoragePlugin({
+      alwaysInsertFields: azureStorageOptions.alwaysInsertFields,
       collections: collectionsWithAdapter,
     })(config)
   }

packages/storage-gcs/src/index.ts

@@ -21,6 +21,17 @@ import { getHandler } from './staticHandler.js'
 export interface GcsStorageOptions {
   acl?: 'Private' | 'Public'
 
+  /**
+   * When enabled, fields (like the prefix field) will always be inserted into
+   * the collection schema regardless of whether the plugin is enabled. This
+   * ensures a consistent schema across all environments.
+   *
+   * This will be enabled by default in Payload v4.
+   *
+   * @default false
+   */
+  alwaysInsertFields?: boolean
+
   /**
    * The name of the bucket to use.
    */
@@ -131,6 +142,7 @@ export const gcsStorage: GcsStoragePlugin =
     }
 
     return cloudStoragePlugin({
+      alwaysInsertFields: gcsStorageOptions.alwaysInsertFields,
       collections: collectionsWithAdapter,
     })(config)
   }

packages/storage-r2/src/index.ts

@@ -15,6 +15,17 @@ import { getHandleUpload } from './handleUpload.js'
 import { getHandler } from './staticHandler.js'
 
 export interface R2StorageOptions {
+  /**
+   * When enabled, fields (like the prefix field) will always be inserted into
+   * the collection schema regardless of whether the plugin is enabled. This
+   * ensures a consistent schema across all environments.
+   *
+   * This will be enabled by default in Payload v4.
+   *
+   * @default false
+   */
+  alwaysInsertFields?: boolean
+
   bucket: R2Bucket
   /**
    * Collection options to apply the R2 adapter to.
@@ -69,6 +80,7 @@ export const r2Storage: R2StoragePlugin =
     }
 
     return cloudStoragePlugin({
+      alwaysInsertFields: r2StorageOptions.alwaysInsertFields,
       collections: collectionsWithAdapter,
     })(config)
   }