Skip to content

Commit d6a03ee

Browse files
authored
docs: adds options table to payload-wide upload options (#10904)
<!-- Thank you for the PR! Please go through the checklist below and make sure you've completed all the steps. Please review the [CONTRIBUTING.md](https://github.com/payloadcms/payload/blob/main/CONTRIBUTING.md) document in this repository if you haven't already. The following items will ensure that your PR is handled as smoothly as possible: - PR Title must follow conventional commits format. For example, `feat: my new feature`, `fix(plugin-seo): my fix`. - Minimal description explained as if explained to someone not immediately familiar with the code. - Provide before/after screenshots or code diffs if applicable. - Link any related issues/discussions from GitHub or Discord. - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Fixes # --> ### What? This PR adds a table to the [Payload-wide Upload Options](https://payloadcms.com/docs/upload/overview#payload-wide-upload-options) section of the docs. ### Why? To give users more insight into the customization options provided out-of-the-box with uploads. Previously, these options were not visible on the docs, forcing users to inspect source code to see how they can customize their global upload settings. It wasn't clear, for example, that a `fileSize` limit would not produce a 413 in a response by default, but would truncate the file contents instead. ### How? Changes to `docs/upload/overview.mdx`.
1 parent 3f80c59 commit d6a03ee

File tree

1 file changed

+18
-1
lines changed

1 file changed

+18
-1
lines changed

docs/upload/overview.mdx

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,24 @@ _An asterisk denotes that an option is required._
113113

114114
### Payload-wide Upload Options
115115

116-
Upload options are specifiable on a Collection by Collection basis, you can also control app wide options by passing your base Payload Config an `upload` property containing an object supportive of all `Busboy` configuration options. [Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control.
116+
Upload options are specifiable on a Collection by Collection basis, you can also control app wide options by passing your base Payload Config an `upload` property containing an object supportive of all `Busboy` configuration options.
117+
118+
| Option | Description |
119+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120+
| **`abortOnLimit`** | A boolean that, if `true`, returns HTTP 413 if a file exceeds the file size limit. If `false`, the file is truncated. Defaults to `false`. |
121+
| **`createParentPath`** | Set to `true` to automatically create a directory path when moving files from a temporary directory or buffer. Defaults to `false`. |
122+
| **`debug`** | A boolean that turns upload process logging on if `true`, or off if `false`. Useful for troubleshooting. Defaults to `false`. |
123+
| **`limitHandler`** | A function which is invoked if the file is greater than configured limits. |
124+
| **`parseNested`** | Set to `true` to turn `req.body` and `req.files` into nested structures. By default `req.body` and `req.files` are flat objects. Defaults to `false`. |
125+
| **`preserveExtension`** | Preserves file extensions with the `safeFileNames` option. Limits file names to 3 characters if `true` or a custom length if a `number`, trimming from the start of the extension. |
126+
| **`responseOnLimit`** | A `string` that is sent in the Response to a client if the file size limit is exceeded when used with `abortOnLimit`. |
127+
| **`safeFileNames`** | Set to `true` to strip non-alphanumeric characters except dashes and underscores. Can also be set to a regex to determine what to strip. Defaults to `false`. |
128+
| **`tempFileDir`** | A `string` path to store temporary files used when the `useTempFiles` option is set to `true`. Defaults to `'./tmp'`. |
129+
| **`uploadTimeout`** | A `number` that defines how long to wait for data before aborting, specified in milliseconds. Set to `0` to disable timeout checks. Defaults to `60000`. |
130+
| **`uriDecodeFileNames`** | Set to `true` to apply uri decoding to file names. Defaults to `false`. |
131+
| **`useTempFiles`** | Set to `true` to store files to a temporary directory instead of in RAM, reducing memory usage for large files or many files. |
132+
133+
[Click here](https://github.com/mscdex/busboy#api) for more documentation about what you can control with `Busboy`.
117134

118135
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:
119136

0 commit comments

Comments
 (0)