Media and image optimization
The uploads collection, file guard, ownership and uploads.imageOptimization.
On this page
Uploaded files live in the uploads collection. Its slug and storage directory are set with the uploads plugin option (uploads: { slug: 'media', staticDir: 'media' }).
The uploads collectionLink to this section
The default slug is uploads, with local storage under storage/uploads. Folders and trash are enabled by default. alt stores the image's alternative text; uploadedBy stores its owner. Relationships in built-in fields follow a configured uploads slug.
File guardLink to this section
FileGuard checks a selected Admin file before submission. It clears files above uploads.maxFileSize or outside uploads.allowedMimeTypes and shows an error. The default maximum is 100 MiB. MIME entries match prefixes; an empty list allows all types. Unknown browser MIME types bypass that client-side MIME check.
A server beforeOperation hook rejects oversized create/update uploads before image processing or storage, with a 400 response. Set maxFileSize: 0 to remove the size limit. allowedMimeTypes is the Admin check, so do not treat it as server-side MIME validation for arbitrary API uploads.
Ownership and accessLink to this section
Creation records the signed-in user's ID in uploadedBy. Public reads are allowed so website media can load. Signed-in users with uploads.read see all uploads; other signed-in users see only their own. Update/delete capabilities allow changes to any upload; without them, access is filtered to the user's own uploads. Changing ownership itself requires uploads.update and the sidebar field is read-only in Admin.
Keep useful alternative text on informative images. The Image block renders an empty alt attribute when the upload has no authored alt.
Uploading requires the uploads.create capability; see Access control. Changing an upload's alt text revalidates every page; see Revalidation.
Image optimizationLink to this section
With the defaults, the maximum width is 2560 pixels and JPEG/PNG quality is 60. Uploaded JPEGs and PNGs are resized to a maximum width and re-compressed before Payload writes them; a PNG with no real transparency is converted to JPEG (filename and mime type follow). Set uploads: { imageOptimization: false } to turn it off, or pass { maxWidth, jpegQuality, convertPngToJpeg, pngQuality } to tune it.
It does not run on client uploads. With Payload's clientUploads the browser sends the file straight to storage, so by the time the document is created the object already exists under its original name — @payloadcms/plugin-cloud-storage skips re-uploading it, and re-encoding or renaming it here would leave the document pointing at an object that was never written. Optimize those images before upload, or in your storage pipeline.