Uploads

Here are some common use cases of Uploads:

Creating a “Media Library” that contains images for use throughout your site or app
Building a Gated Content library where users need to sign up to gain access to downloadable assets like ebook PDFs, whitepapers, etc.
Storing publicly available, downloadable assets like software, ZIP files, MP4s, etc.

By simply enabling Upload functionality on a Collection, FrogBot will automatically transform your Collection into a robust file management / storage solution. The following modifications will be made:

filename, mimeType, and filesize fields will be automatically added to your Collection. Optionally, if you declare image sizes as variants on sharpTransformer, a variants group will also be added containing auto-resized image sizes and filenames.
The Admin Panel will modify its built-in List component to show a thumbnail for each upload within the List View
The Admin Panel will modify its Edit view(s) to add a new set of corresponding Upload UI which will allow for file upload
The create, update, and delete Collection operations will be modified to support file upload, re-upload, and deletion

Enabling Uploads

Every FrogBot Collection can opt-in to supporting Uploads by specifying the upload property on the Collection’s config to either true or to an object containing upload options.

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    staticDir: 'media',
    adminThumbnail: 'thumbnail',
    mimeTypes: ['image/*'],
  },
  fields: [
    {
      name: 'alt',
      type: 'text',
    },
  ],
}

Collection Upload Options

Set upload: true for the defaults, or pass an object with these options. Image processing (sizes, resizing, format, trim, metadata, crop and focal point) is configured on sharpTransformer; see Image Sizes.

Option	Type	Default	Description
`staticDir`	`string`	The collection slug	Folder where files are stored: an absolute path, or a path relative to the server’s working directory (`/app` in the template `Dockerfile`). Ignored when `disableLocalStorage` is `true`.
`mimeTypes`	`string[]`	Any type	MIME types or wildcards the file picker offers and the server accepts, such as `['image/*', 'application/pdf']`. Setting it also skips the restricted file type check. More
`adminThumbnail`	`string \| ({ doc }) => string \| false \| null`	The original file, for images	Variant name, or a function returning a full URL, used for thumbnails in the Admin Panel. More
`crop`	`boolean`	`true`	Shows the cropping tool in the Admin Panel. A `crop` set on `sharpTransformer` for this collection replaces it. More
`focalPoint`	`boolean`	`true`	Shows the focal point selector in the Admin Panel. A `focalPoint` set on `sharpTransformer` for this collection replaces it. More
`bulkUpload`	`boolean`	`true`	Allows uploading several files at once from the list view.
`filesRequiredOnCreate`	`boolean`	`true`	Requires a file when a document is created.
`hideFileInputOnCreate`	`boolean`	`false`	Hides the file input when creating a document in the Admin Panel, for files your code generates.
`hideRemoveFile`	`boolean`	`false`	Hides the control for removing an existing file while editing.
`displayPreview`	`boolean`	`false`	Shows a preview of the selected file in upload fields that relate to this collection. An upload field’s own `displayPreview` overrides it.
`cacheTags`	`boolean`	`true`	Appends a cache tag to Admin Panel thumbnail URLs. Disable it when your CDN rejects unknown query parameters.
`pasteURL`	`false \| { allowList: AllowList }`	Client-side fetching enabled	Controls uploading from a pasted URL. `false` disables it; an `allowList` fetches matching URLs on the server instead. More
`skipSafeFetch`	`boolean \| AllowList`	`false`	Skips the server’s safe-fetch checks, which block requests to private networks, for every URL (`true`) or for matching URLs.
`externalFileHeaderFilter`	`(headers, context?) => Record<string, string>`	Forwards only the request’s cookies, without `frogbot`-prefixed cookies for other origins	Builds the headers sent when the server fetches a file from a URL. It receives every incoming request header and `{ isSameOrigin, url }` for each request and redirect. Remove session cookies yourself when you set it.
`filenameCompoundIndex`	`string[]`	A unique index on `filename`	Field names to combine into a compound unique index instead, for example to allow the same filename in different folders.
`modifyResponseHeaders`	`({ headers }) => Headers \| void`	None	Changes the response headers when a file is served. Mutate `headers` or return a new `Headers` object. More
`handlers`	`((req, { doc, headers?, params }) => Response \| void \| Promise<Response \| void>)[]`	None	Run in order when a file is requested. The first handler that returns a `Response` sends it; otherwise the file is served normally. `req` is the incoming `FrogBotRequest`, with `req.frogbot`. `params` holds `collection`, `filename`, and optional `operation`, `prefix` and `uploadReference`.
`disableLocalStorage`	`boolean`	`false`	Stops writing files to disk. Storage adapters set this for you. More
`allowRestrictedFileTypes`	`boolean`	`false`	Allows restricted file types. Has no effect when `mimeTypes` is set, because that already skips the check.
`admin`	`{ components?: { controls?: FrogBotComponent[] } }`	None	`controls` adds components beside the Select file and Paste URL buttons in the upload area.
`adapter`	`string`	None	Name of the storage adapter handling this collection. Storage adapters set it; you don’t need to.

FrogBot-wide Upload Options

The root upload option configures how multipart requests are parsed for every upload-enabled collection. It combines file handling options with the options of the busboy parser. Root bodyParser options are applied first, and upload options override them.

Option	Type	Default	Description
`transformers`	`UploadTransformer[]`	`[]`	File transformers that process uploads and serve transformed files, in order, such as `sharpTransformer()`. See Image Sizes.
`limits`	`Limits`	See Upload limits	Size and count limits for each request.
`requestSizeLimit`	`number`	`52428800` (50 MB)	Maximum size in bytes of the whole multipart request, including files, fields, and boundaries. Larger requests fail with HTTP 413. Must be a non-negative safe integer, or `Infinity` to disable the check.
`abortOnLimit`	`boolean`	`true`	When a file exceeds `limits.fileSize`, fail the request with HTTP 413 and `responseOnLimit`. When `false`, the file is truncated and marked `truncated: true`.
`responseOnLimit`	`string`	`'File size limit has been reached'`	Error message returned when `abortOnLimit` rejects a file.
`limitHandler`	`boolean \| ({ request, size }) => void`	`false`	Called when a file exceeds `limits.fileSize`, before `abortOnLimit` applies. Throwing fails the request.
`useTempFiles`	`boolean`	`false`	Writes incoming files to `tempFileDir` instead of memory, reducing memory use for large files.
`tempFileDir`	`string`	`'tmp'`	Folder for temporary files when `useTempFiles` is `true`, absolute or relative to the working directory.
`uploadTimeout`	`number`	`60000`	Milliseconds to wait for more file data before failing the request. `0` disables the timeout.
`safeFileNames`	`boolean \| RegExp`	`false`	`true` strips every character except letters, numbers, dashes, and underscores from file names. A regular expression strips its matches instead.
`preserveExtension`	`boolean \| number`	`false`	Keeps the extension when `safeFileNames` is set. `true` keeps up to 3 characters; a number sets the maximum length.
`uriDecodeFileNames`	`boolean`	`false`	URI-decodes file names.
`parseNested`	`boolean`	`false`	Turns flat keys such as `hobbies[0]` into nested objects and arrays in the parsed fields and files.
`createParentPath`	`boolean`	`false`	Creates missing parent folders when a parsed file is moved with `mv`.
`debug`	`boolean`	`false`	Logs parsing steps, for troubleshooting.
`defCharset`	`string`	`'utf8'`	Character set for parts that don’t declare one.
`defParamCharset`	`string`	`'utf8'`	Character set for part header parameters, such as file names, that don’t declare one.
`preservePath`	`boolean`	`false`	Keeps the folder path in file names instead of only the base name.
`highWaterMark`	`number`	Node.js stream default	Buffer size for the parser stream.
`fileHwm`	`number`	Node.js stream default	Buffer size for each file stream.
`headers`	`IncomingHttpHeaders`	The request headers	Accepted for type compatibility. FrogBot always passes the request’s own headers to the parser, so a configured value has no effect.

Upload limits

Option	Type	Default	Description
`fileSize`	`number`	`20971520` (20 MB)	Maximum size in bytes of each file. What happens when a file exceeds it depends on `abortOnLimit`.
`files`	`number`	`3`	Maximum number of files per request. More files fail the request with HTTP 413.
`fields`	`number`	`20`	Maximum number of non-file fields per request. More fields fail the request with HTTP 413.
`fieldSize`	`number`	`1048576` (1 MB)	Maximum size in bytes of each field value. A larger value fails the request with HTTP 413.
`fieldNameSize`	`number`	`100`	Maximum size in bytes of each field name. A longer name fails the request with HTTP 413.
`parts`	`number`	Unlimited	Maximum number of fields plus files per request. More parts fail the request with HTTP 413.
`headerPairs`	`number`	`2000`	Maximum number of header key-value pairs parsed for each part.

A common example of what you might want to customize within FrogBot-wide Upload options would be to increase the allowed fileSize of uploads sent to FrogBot:

import { buildConfig } from 'frogbot'

export default buildConfig({
  collections: [
    {
      slug: 'media',
      fields: [
        {
          name: 'alt',
          type: 'text',
        },
      ],
      upload: true,
    },
  ],
  upload: {
    limits: {
      fileSize: 5000000, // 5MB, written in bytes
    },
  },
})

Custom filename via hooks

You can customize the filename before it’s uploaded to the server by using a beforeOperation hook.

beforeOperation: [
  ({ req, operation }) => {
    if ((operation === 'create' || operation === 'update') && req.file) {
      req.file.name = 'test.jpg'
    }
  },
],

The req.file object will have additional information about the file, such as mimeType and extension, and you also have full access to the file data itself. The filename from here will also be threaded to image sizes if they’re enabled.

Image Sizes

If you declare image sizes, FrogBot will automatically crop and resize your uploads to fit each of them. The Admin Panel shows every size, with its width, height, and file size. Image sizes, declared as variants, and the rest of the image options are configured on sharpTransformer from @frogbotai/transformer-sharp, which resizes with sharp. The blank template installs it. Without a transformer, FrogBot stores uploads as they are and shows no crop or focal point tools.

import { sharpTransformer } from '@frogbotai/transformer-sharp'
import { buildConfig } from 'frogbot'

export default buildConfig({
  // required options omitted
  upload: {
    transformers: [
      sharpTransformer({
        collections: {
          media: {
            variants: [
              { name: 'thumbnail', width: 400, height: 300, position: 'centre' },
              { name: 'card', width: 768, height: 1024, position: 'centre' },
              // Without a height, the image keeps its aspect ratio.
              { name: 'tablet', width: 1024, position: 'centre' },
            ],
          },
        },
      }),
    ],
  },
})

Each entry in collections accepts these options:

Option	Type	Default	Description
`variants`	`ImageSize[]`	None	Resized copies to generate for each uploaded image. Adds a `variants` group to the collection.
`formatOptions`	`{ format, options? }`	None	Converts the original image with `sharp`’s `toFormat`. Each variant has its own `formatOptions`.
`resizeOptions`	`ResizeOptions`	None	`sharp` resize options applied to the original image.
`trimOptions`	`TrimOptions`	None	`sharp` trim options applied to the original image.
`constructorOptions`	`SharpOptions`	None	`sharp` constructor options used when the original image is loaded.
`withMetadata`	`boolean \| ({ metadata, req }) => Promise<boolean>`	`false`	Keeps image metadata, such as EXIF, in processed files.
`crop`	`boolean`	`true`	Shows the cropping tool in the Admin Panel. More
`focalPoint`	`boolean`	`true`	Shows the focal point selector in the Admin Panel. More

sharpTransformer({ dynamic: true }) also resizes on request, through ?width= and ?height= on the file URL. Registering any transformer changes the file endpoint: a file is served only when it belongs to an upload document.

Image size options

Each entry in variants is an ImageSize. Besides the options below, it accepts every sharp resize option.

Option	Type	Default	Description
`name`	`string`	Required	Key of this size in the document’s `variants` group.
`width`	`number`	None	Target width in pixels. With only one of `width` or `height`, the other follows the original aspect ratio.
`height`	`number`	None	Target height in pixels.
`fit`	`'cover' \| 'contain' \| 'fill' \| 'inside' \| 'outside'`	`'cover'`	How the image fits both dimensions.
`position`	`string \| number`	`'centre'`	Which part of the image to keep when `fit` is `'cover'` or `'contain'`, such as `'top'` or `'entropy'`.
`background`	`string \| { r, g, b, alpha }`	Black	Fill color when `fit` is `'contain'`.
`kernel`	`'nearest' \| 'linear' \| 'cubic' \| 'mitchell' \| 'lanczos2' \| 'lanczos3' \| 'mks2013' \| 'mks2021'`	`'lanczos3'`	Resampling kernel used when reducing the image.
`withoutEnlargement`	`boolean`	`undefined`	Handles images smaller than the size. See Handling Image Enlargement.
`withoutReduction`	`boolean`	`false`	Don’t shrink images larger than the size. When `true`, `fit` defaults to `'contain'` and `position` to `'left top'`.
`fastShrinkOnLoad`	`boolean`	`true`	Lets `sharp` shrink JPEG and WebP images while decoding. Faster, but can produce slightly different results.
`formatOptions`	`{ format, options? }`	The original format	Converts this size with `sharp`’s `toFormat`.
`trimOptions`	`TrimOptions`	None	`sharp` trim options applied after resizing.
`generateImageName`	`({ originalName, sizeName, extension, width, height }) => string`	`${originalName}-${width}x${height}.${extension}`	Builds the file name of the resized image. More
`admin`	`{ disabled?: { groupBy?, column?, filter? } }`	All `false`	Hides this size’s fields from list view controls. More
`crop`	`string`	None	Deprecated and has no effect. Use `position`.

When a document has a focal point and the size’s aspect ratio differs from the image, FrogBot crops around the focal point instead of applying position, unless fit is 'contain' or 'inside'.

Admin List View Options

Each image size also supports admin options to control whether it appears in the Admin Panel list view.

{
  name: 'thumbnail',
  width: 400,
  height: 300,
  admin: {
    disabled: {
      groupBy: true, // hide from list view groupBy options
      column: true, // hide from list view columns
      filter: true, // hide from list view filters
    },
  },
}

Option	Type	Default	Description
`disabled.groupBy`	`boolean`	`false`	Hides this image size from the list view’s group-by options.
`disabled.column`	`boolean`	`false`	Hides this image size from the list view’s selectable columns.
`disabled.filter`	`boolean`	`false`	Hides this image size from the list view’s filters.

This is useful for hiding large or rarely used image sizes from the list view UI while still keeping them available in the API.

Accessing the resized images in hooks

All auto-resized images are exposed to be reused in hooks and similar via an object that is bound to req.payloadUploadSizes. The object will have keys for each size generated, and each key will be set equal to a buffer containing the file data.

Handling Image Enlargement

When an uploaded image is smaller than the defined image size, we have 3 options: withoutEnlargement: undefined | false | true

undefined [default]: uploading images with smaller width AND height than the image size will return null
false: always enlarge images to the image size
true: if the image is smaller than the image size, return the original image

Custom file name per size

Each image size supports a generateImageName function that can be used to generate a custom file name for the resized image. This function receives the original file name, the resize name, the extension, height and width as arguments.

{
  name: 'thumbnail',
  width: 400,
  height: 300,
  generateImageName: ({ height, sizeName, extension, width }) => {
    return `custom-${sizeName}-${height}-${width}.${extension}`
  },
}

Crop and Focal Point Selector

This feature is only available for image file types, with sharpTransformer registered. Setting crop: false and focalPoint: false on sharpTransformer({ collections }) for a collection disables the respective selector in the Admin Panel. Cropping changes the main image. Variants are generated from the retained original, so cropping the main image does not also crop them. The focal point controls how variants are framed. The focal point selector is shown only when the collection has variants or image adjustments (resizeOptions, formatOptions, trimOptions, constructorOptions, or withMetadata), or when focalPoint is true.

Disabling Local Upload Storage

If you are using a plugin to send your files off to a third-party file storage host or CDN, like Amazon S3 or similar, you may not want to store your files locally at all. You can prevent FrogBot from writing files to disk by specifying disableLocalStorage: true on your collection’s upload config.

Admin Thumbnails

You can specify how FrogBot retrieves admin thumbnails for your upload-enabled Collections with one of the following:

adminThumbnail as a string, equal to one of your variant names (declared on sharpTransformer).

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    // highlight-start
    adminThumbnail: 'small',
    // highlight-end
  },
}

adminThumbnail as a function that takes the document’s data and sends back a full URL to load the thumbnail.

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    // highlight-start
    adminThumbnail: ({ doc }) =>
      `https://google.com/custom-path-to-file/${doc.filename}`,
    // highlight-end
  },
}

Customizing the Upload UI

Use the public UploadField component to customize a field that selects uploaded documents while retaining its form integration.

Upload Component Configuration

Set admin.components.Field on an Upload field in your Collection Config:

import type { CollectionConfig } from 'frogbot'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'files',
      admin: {
        components: {
          Field: '/components/CustomUploadField#CustomUploadField',
        },
      },
    },
  ],
}

Building Custom Upload Components

Wrap UploadField from @frogbotai/ui/admin and forward the provided props, including permissions and read-only state. Render this component through the field slot so it receives the Admin Panel’s form and upload providers.

Basic Example

Client Component (src/components/CustomUploadField.tsx):

'use client'

import { UploadField } from '@frogbotai/ui/admin'
import type { UploadFieldClientProps } from 'frogbot'

export const CustomUploadField = (props: UploadFieldClientProps) => {
  return (
    <div>
      <p>Select an image for the post.</p>
      <UploadField {...props} />
    </div>
  )
}

Available Hooks and Components

When building custom upload components, you have access to several useful hooks and components from @frogbotai/ui/admin:

Hook / Component	Description
`useField()`	Access and manipulate form field state.
`useBulkUpload()`	Access the bulk upload context.
`UploadField`	Form-connected upload relationship control.
`UploadInput`	Lower-level upload relationship input requiring `value` and `onChange` wiring.

Custom Upload Fields vs. Custom Upload Collections

The example above customizes an upload relationship field. Replacing an upload collection’s file editor is a separate extension point:

Approach	Configuration	Use Case
Upload Collection Customization	`admin.components.edit.Upload`	Customize the UI when editing documents in an upload-enabled collection (e.g., the Media collection edit view)
Upload Field Customization	`admin.components.Field` on an upload field	Customize the field that references uploads in other collections (e.g., a “Featured Image” field on a Posts collection)

@frogbotai/ui/admin does not export the complete collection Upload editor. Keep the default collection editor unless you are implementing its file, form, and upload-state integration yourself. UploadField and UploadInput select related documents; they are not replacements for that collection slot.

Component Export Syntax

Custom components are referenced using file paths. Both default exports and named exports are supported:

Field: {
  path: '/components/CustomUploadField',
  exportName: 'CustomUploadField',
}

Component paths identify the module and export to render.

Restricted File Types

Possibly problematic file types are automatically restricted from being uploaded to your application. If your Collection has defined mimeTypes or has set allowRestrictedFileTypes to true, restricted file verification will be skipped. Restricted file types and extensions:

File Extensions	MIME Type
`exe`, `dll`	`application/x-msdownload`
`exe`, `com`, `app`, `action`	`application/x-executable`
`bat`, `cmd`	`application/x-msdos-program`
`exe`, `com`	`application/x-ms-dos-executable`
`dmg`	`application/x-apple-diskimage`
`deb`	`application/x-debian-package`
`rpm`	`application/x-redhat-package-manager`
`exe`, `dll`	`application/vnd.microsoft.portable-executable`
`msi`	`application/x-msi`
`jar`, `ear`, `war`	`application/java-archive`
`desktop`	`application/x-desktop`
`cpl`	`application/x-cpl`
`lnk`	`application/x-ms-shortcut`
`pkg`	`application/x-apple-installer`
`htm`, `html`, `shtml`, `xhtml`	`text/html`
`php`, `phtml`	`application/x-httpd-php`
`js`, `jse`	`text/javascript`
`jsp`	`application/x-jsp`
`py`	`text/x-python`
`rb`	`text/x-ruby`
`pl`	`text/x-perl`
`ps1`, `psc1`, `psd1`, `psh`, `psm1`	`application/x-powershell`
`vbe`, `vbs`	`application/x-vbscript`
`ws`, `wsc`, `wsf`, `wsh`	`application/x-ms-wsh`
`scr`	`application/x-msdownload`
`asp`, `aspx`	`application/x-asp`
`hta`	`application/x-hta`
`reg`	`application/x-registry`
`url`	`application/x-url`
`workflow`	`application/x-workflow`
`command`	`application/x-command`

MimeTypes

Specifying the mimeTypes property can restrict what files are allowed from the user’s file picker. This accepts an array of strings, which can be any valid mimetype or mimetype wildcards Some example values are: image/*, audio/*, video/*, image/png, application/pdf Example mimeTypes usage:

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    mimeTypes: ['image/*', 'application/pdf'], // highlight-line
  },
}

Uploading Files

To upload a file, use your collection’s create endpoint. Send it all the data that your Collection requires, as well as a file key containing the file that you’d like to upload. Send your request as a multipart/form-data request, using FormData if possible.

const fileInput = document.querySelector('#your-file-input')
const formData = new FormData()

formData.append('file', fileInput.files[0])

// Replace with the fields defined in your upload-enabled collection.
// The example below includes an optional field like 'title'.
formData.append(
  '_payload',
  JSON.stringify({
    title: 'Example Title',
    description: 'An optional description for the file',
  }),
)

fetch('api/:upload-slug', {
  method: 'POST',
  body: formData,
  /**
   * Do not manually add the Content-Type Header
   * the browser will handle this.
   *
   * headers: {
   *  'Content-Type': 'multipart/form-data'
   * }
   */
})

Uploading Files stored locally

If you want to upload a file stored on your machine directly using the frogbot.create method, for example, during a seed script, you can use the filePath property to specify the local path of the file.

const localFilePath = path.resolve(__dirname, filename)

await frogbot.create({
  collection: 'media',
  overrideAccess: true,
  data: {
    alt,
  },
  filePath: localFilePath,
})

The data property should still include all the required fields of your media collection.

Uploading Files from Remote URLs

The pasteURL option allows users to fetch files from remote URLs by pasting them into an Upload field. This option is enabled by default and can be configured to either allow unrestricted client-side fetching or restrict server-side fetching to specific trusted domains. By default, FrogBot uses client-side fetching, where the browser downloads the file directly from the provided URL. However, client-side fetching will fail if the URL’s server has CORS restrictions, making it suitable only for internal URLs or public URLs without CORS blocks. To fetch files from restricted URLs that would otherwise be blocked by CORS, use server-side fetching by configuring the pasteURL option with an allowList of trusted domains. This method ensures that FrogBot downloads the file on the server and streams it to the browser. However, for security reasons, only URLs that match the specified allowList will be allowed.

Configuration Example

Here’s how to configure the pasteURL option to control remote URL fetching:

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    pasteURL: {
      allowList: [
        {
          hostname: 'frogbot.com', // required
          pathname: '',
          port: '',
          protocol: 'https',
          search: '',
        },
        {
          hostname: 'example.com',
          pathname: '/images/*',
        },
      ],
    },
  },
}

You can also adjust server-side fetching at the upload level as well, this does not effect the CORS policy like the pasteURL option does, but it allows you to skip the safe fetch check for specific URLs.

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    skipSafeFetch: [
      {
        hostname: 'example.com',
        pathname: '/images/*',
      },
    ],
  },
}

Accepted Values for `pasteURL`

Value	Description
`undefined`	Default. The browser fetches pasted URLs itself, so URLs blocked by CORS fail.
`false`	Removes the Paste URL option from the upload area.
`{ allowList }`	The server fetches pasted URLs that match an `allowList` entry. Other URLs, and redirects to URLs outside the list, are rejected.

`AllowItem` Properties

A URL is allowed when it matches every property set on at least one entry. Unset properties match anything.

Option	Type	Default	Description
`hostname`	`string`	Required	Exact hostname, such as `example.com`.
`pathname`	`string`	Any path	Path pattern. `` matches within one path segment and `` matches across segments, as in `/images/`. A trailing `/` also matches without it.
`port`	`string`	Any port	Exact port, such as `'3000'`. A URL that uses the protocol’s default port has an empty port.
`protocol`	`'http' \| 'https'`	Any protocol	Required protocol, without the colon.
`search`	`string`	Any query string	Exact query string, including the leading `?`, such as `'?version=1'`.

skipSafeFetch accepts the same AllowItem array.

Access Control

All files that are uploaded to each Collection automatically support the read Access Control function from the Collection itself. You can use this to control who should be allowed to see your uploads, and who should not.

Modifying response headers

You can modify the response headers for files by specifying the modifyResponseHeaders option in your upload config. This option accepts an object with existing headers and allows you to manipulate the response headers for media files.

Modifying existing headers

With this method you can directly interface with the Headers object and modify the existing headers to append or remove headers.

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    modifyResponseHeaders: ({ headers }) => {
      headers.set('X-Frame-Options', 'DENY') // You can directly set headers without returning
    },
  },
}

Return new headers

You can also return a new Headers object with the modified headers. This is useful if you want to set new headers or remove existing ones.

import type { CollectionConfig } from 'frogbot'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    modifyResponseHeaders: ({ headers }) => {
      const newHeaders = new Headers(headers) // Copy existing headers
      newHeaders.set('X-Frame-Options', 'DENY') // Set new header

      return newHeaders
    },
  },
}

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Enabling Uploads

Collection Upload Options

FrogBot-wide Upload Options

Upload limits

Custom filename via hooks

Image Sizes

Image size options

Admin List View Options

Accessing the resized images in hooks

Handling Image Enlargement

Custom file name per size

Crop and Focal Point Selector

Disabling Local Upload Storage

Admin Thumbnails

Customizing the Upload UI

Upload Component Configuration

Building Custom Upload Components

Basic Example

Available Hooks and Components

Custom Upload Fields vs. Custom Upload Collections

Component Export Syntax

Restricted File Types

MimeTypes

Uploading Files

Uploading Files stored locally

Uploading Files from Remote URLs

Configuration Example

Accepted Values for `pasteURL`

`AllowItem` Properties

Access Control

Modifying response headers

Modifying existing headers

Return new headers

​Enabling Uploads

​Collection Upload Options

​FrogBot-wide Upload Options

​Upload limits

​Custom filename via hooks

​Image Sizes

​Image size options

​Admin List View Options

​Accessing the resized images in hooks

​Handling Image Enlargement

​Custom file name per size

​Crop and Focal Point Selector

​Disabling Local Upload Storage

​Admin Thumbnails

​Customizing the Upload UI

​Upload Component Configuration

​Building Custom Upload Components

​Basic Example

​Available Hooks and Components

​Custom Upload Fields vs. Custom Upload Collections

​Component Export Syntax

​Restricted File Types

​MimeTypes

​Uploading Files

​Uploading Files stored locally

​Uploading Files from Remote URLs

​Configuration Example

Accepted Values for pasteURL

AllowItem Properties

​Access Control

​Modifying response headers

​Modifying existing headers

​Return new headers

Enabling Uploads

Collection Upload Options

FrogBot-wide Upload Options

Upload limits

Custom filename via hooks

Image Sizes

Image size options

Admin List View Options

Accessing the resized images in hooks

Handling Image Enlargement

Custom file name per size

Crop and Focal Point Selector

Disabling Local Upload Storage

Admin Thumbnails

Customizing the Upload UI

Upload Component Configuration

Building Custom Upload Components

Basic Example

Available Hooks and Components

Custom Upload Fields vs. Custom Upload Collections

Component Export Syntax

Restricted File Types

MimeTypes

Uploading Files

Uploading Files stored locally

Uploading Files from Remote URLs

Configuration Example

Accepted Values for `pasteURL`

`AllowItem` Properties

Access Control

Modifying response headers

Modifying existing headers

Return new headers