130 lines
6.0 KiB
Plaintext
130 lines
6.0 KiB
Plaintext
---
|
|
title: Uploads
|
|
label: Overview
|
|
order: 10
|
|
desc: Payload is a headless CMS and application framework.
|
|
keywords: uploads, images, media, overview, documentation, Content Management System, cms, headless, javascript, node, react, express
|
|
---
|
|
|
|
<Banner>
|
|
Payload provides for everything you need to enable file upload, storage, and management directly on your server—including extremely powerful file access control.
|
|
</Banner>
|
|
|
|
|
|
*Admin panel screenshot depicting a Media Collection with Upload enabled*
|
|
|
|
**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, Payload will automatically transform your Collection into a robust file management / storage solution. The following modifications will be made:**
|
|
|
|
1. `filename`, `mimeType`, and `filesize` fields will be automatically added to your Collection. Optionally, if you pass `imageSizes` to your Collection's Upload config, a [`sizes`](#image-sizes) array will also be added containing auto-resized image sizes and filenames.
|
|
1. The Admin panel will modify its built-in `List` component to show a thumbnail gallery of your Uploads instead of the default Table view
|
|
1. The Admin panel will modify its `Edit` view(s) to add a new set of corresponding Upload UI which will allow for file upload
|
|
1. The `create`, `update`, and `delete` Collection operations will be modified to support file upload, re-upload, and deletion
|
|
|
|
### Enabling Uploads
|
|
|
|
Every Payload 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.
|
|
|
|
<Banner type="success">
|
|
<strong>Tip:</strong><br/>
|
|
A common pattern is to create a <strong>Media</strong> collection and enable <strong>upload</strong> on that collection.
|
|
</Banner>
|
|
|
|
#### Collection Upload Options
|
|
|
|
| Option | Description |
|
|
| ---------------------- | -------------|
|
|
| **`staticURL`** * | The base URL path to use to access you uploads. Example: `/media` |
|
|
| **`staticDir`** * | The folder directory to use to store media in. Can be either an absolute path or relative to the directory that contains your config. |
|
|
| **`imageSizes`** | If specified, image uploads will be automatically resized in accordance to these image sizes. [More](#image-sizes) |
|
|
| **`adminThumbnail`** | Which of your provided image sizes to use for the admin panel's thumbnail. Typically a size around 500x500px or so works well. |
|
|
|
|
*An asterisk denotes that a property above is required.*
|
|
|
|
**Example Upload collection:**
|
|
```js
|
|
const Media = {
|
|
slug: 'media',
|
|
upload: {
|
|
staticURL: '/media',
|
|
staticDir: 'media',
|
|
imageSizes: [
|
|
{
|
|
name: 'thumbnail',
|
|
width: 400,
|
|
height: 300,
|
|
crop: 'centre',
|
|
},
|
|
{
|
|
name: 'card',
|
|
width: 768,
|
|
height: 1024,
|
|
crop: 'centre',
|
|
}
|
|
],
|
|
adminThumbnail: 'thumbnail',
|
|
}
|
|
}
|
|
```
|
|
|
|
### Payload-wide Upload Options
|
|
|
|
Payload relies on the [`express-fileupload`](https://www.npmjs.com/package/express-fileupload) package to manage file uploads in Express. In addition to the Upload options specifiable on a Collection by Collection basis, you can also control the `express-fileupload` options by passing your base Payload config an `upload` property containing an object supportive of all `express-fileupload` properties which use `Busboy` under the hood. [Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control.
|
|
|
|
A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed `fileSize` of uploads sent to Payload:
|
|
|
|
```js
|
|
import { buildConfig } from 'payload/config';
|
|
|
|
export default buildConfig({
|
|
serverURL: 'http://localhost:3000',
|
|
collections: [
|
|
{
|
|
slug: 'media',
|
|
fields: [
|
|
{
|
|
name: 'alt',
|
|
type: 'text',
|
|
},
|
|
],
|
|
upload: true,
|
|
},
|
|
],
|
|
upload: {
|
|
limits: {
|
|
fileSize: 5000000, // 5MB, written in bytes
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### Image Sizes
|
|
|
|
If you specify an array of `imageSizes` to your `upload` config, Payload will automatically crop and resize your uploads to fit each of the sizes specified by your config.
|
|
|
|
The Payload Admin panel will also automatically display all available files, including width, height, and filesize, for each of your uploaded files.
|
|
|
|
Behind the scenes, Payload relies on [`sharp`](https://sharp.pixelplumbing.com/api-resize#resize) to perform its image resizing. You can specify additional options for `sharp` to use while resizing your images.
|
|
|
|
### Uploading Files
|
|
|
|
<Banner type="warning">
|
|
<strong>Important:</strong><br/>
|
|
Uploading files is currently only possible through the REST and Local APIs due to how GraphQL works. It's difficult and fairly nonsensical to support uploading files through GraphQL.
|
|
</Banner>
|
|
|
|
To upload a file, use your collection's [`create`](/docs/rest-api/overview#collections) 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`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) if possible.
|
|
|
|
[Here is a walkthrough](https://muffinman.io/blog/uploading-files-using-fetch-multipart-form-data/) detailing how to upload files as `multipart/form-data` using React.
|
|
|
|
### Access Control
|
|
|
|
All files that are uploaded to each Collection automatically support the `read` [Access Control](/docs/access-control/overview) function from the Collection itself. You can use this to control who should be allowed to see your uploads, and who should not.
|