asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: improve file uploads example + add section on overriding body size limit (#13250)

Browse Source
This commit is contained in:
Shahed Nasser
2025-08-20 14:07:19 +03:00
committed by GitHub
parent 729cf81395
commit fa16503005
3 changed files with 92 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/book/app/learn/fundamentals/api-routes/parse-body/page.mdx
+46 -28
View File
@@ -8,9 +8,9 @@ In this chapter, you'll learn how to configure the request body parser for your
## Default Body Parser Configuration
The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html), or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
This chapter shares some examples of configuring the body parser for different data types or use cases.
This chapter provides examples of configuring the body parser for different data types or use cases.
---
@@ -18,7 +18,7 @@ This chapter shares some examples of configuring the body parser for different d
If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
To do that, create the file `src/api/middlewares.ts` with the following content:
To do this, create the file `src/api/middlewares.ts` with the following content:
export const preserveHighlights = [
["7", "preserveRawBody", "Enable preserving the raw body data."],
@@ -38,7 +38,7 @@ export default defineMiddlewares({
})
```
The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
The middleware route object passed to `routes` accepts a `bodyParser` property, whose value is a configuration object for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
<Note title="Tip">
@@ -89,26 +89,35 @@ export default defineMiddlewares({
The `sizeLimit` property accepts one of the following types of values:
- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
- A string representing the size limit (for example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
- A number representing the size limit in bytes. For example, `1024` for 1kb.
### Overriding Request Body Size Limit
You can't override the request body size limit for existing routes, such as Medusa's Store and Admin API routes, due to how [middlewares are applied](../middlewares/page.mdx#how-are-middlewares-ordered-and-applied).
If you need to override the request body size limit for a specific route, you can create a custom [API route](../page.mdx) that executes the same functionality as the original route, but with the body size limit you need.
Learn more in the [Override API Routes](../override/page.mdx) chapter.
---
## Configure File Uploads
To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better TypeScript support, install the `@types/multer` package as a development dependency:
```bash npm2yarn
npm install --save-dev @types/multer
```
Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
Then, to configure file uploads for your route, create the file `src/api/middlewares.ts` with the following content:
export const uploadHighlights = [
["4", "upload", "Configure the upload middleware."],
["13", "upload", "Add the upload middleware to the route."],
["13", `"files"`, "Specify the field name for the uploaded files."]
]
```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
@@ -131,29 +140,12 @@ export default defineMiddlewares({
})
```
In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
In the example above, you configure the `multer` middleware to store the uploaded files in memory.
Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
You can then access the uploaded files in your API route handler:
```ts title="src/api/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
) {
const files = req.files as Express.Multer.File[]
// TODO handle files
}
```
The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
### Uploading Files using File Module Provider
The recommended way to upload the files to storage using the configured [File Module Provider](!resources!/infrastructure-modules/file) is to use the [uploadFilesWorkflow](!resources!/references/medusa-workflows/uploadFilesWorkflow):
```ts title="src/api/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { MedusaError } from "@medusajs/framework/utils"
@@ -187,4 +179,30 @@ export async function POST(
}
```
Check out the [uploadFilesWorkflow reference](!resources!/references/medusa-workflows/uploadFilesWorkflow) for details on the expected input and output of the workflow.
The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
To upload the files, you can use the [uploadFilesWorkflow](!resources!/references/medusa-workflows/uploadFilesWorkflow), which uploads the files using the configured [File Module Provider](!resources!/infrastructure-modules/file).
### Test API Route
To test the API route, send a `POST` request to the `/custom` endpoint with the `files` field containing one or more files:
```bash
curl -X POST 'localhost:9000/custom' \
--form 'files=@"/path/to/file.png"'
```
Where `/path/to/file.png` is the path to the file you want to upload.
The request will return a JSON response with the uploaded file information:
```json title="Example Response"
{
"files": [
{
"id": "file_1",
"url": "https://example.com/files/file_1"
}
]
}
```
www/apps/book/generated/edit-dates.mjs
+1 -1
View File
@@ -106,7 +106,7 @@ export const generatedEditDates = {
"app/learn/update/page.mdx": "2025-01-27T08:45:19.030Z",
"app/learn/fundamentals/module-links/query-context/page.mdx": "2025-02-12T16:59:20.963Z",
"app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-08-01T13:16:25.172Z",
"app/learn/fundamentals/api-routes/parse-body/page.mdx": "2025-04-17T08:29:10.145Z",
"app/learn/fundamentals/api-routes/parse-body/page.mdx": "2025-08-20T09:58:37.704Z",
"app/learn/fundamentals/admin/routing/page.mdx": "2025-07-25T07:35:18.038Z",
"app/learn/resources/contribution-guidelines/admin-translations/page.mdx": "2025-02-11T16:57:46.726Z",
"app/learn/resources/contribution-guidelines/docs/page.mdx": "2025-08-20T06:41:30.822Z",
www/apps/book/public/llms-full.txt
+45 -28
View File
@@ -8193,9 +8193,9 @@ In this chapter, you'll learn how to configure the request body parser for your
## Default Body Parser Configuration
The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html) or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
The Medusa application configures the body parser by default to parse JSON, URL-encoded, and text request content types. You can parse other data types by adding the relevant [Express middleware](https://expressjs.com/en/guide/using-middleware.html), or preserve the raw body data by configuring the body parser, which is useful for webhook requests.
This chapter shares some examples of configuring the body parser for different data types or use cases.
This chapter provides examples of configuring the body parser for different data types or use cases.
***
@@ -8203,7 +8203,7 @@ This chapter shares some examples of configuring the body parser for different d
If your API route receives webhook requests, you might want to preserve the raw body data. To do this, you can configure the body parser to parse the raw body data and store it in the `req.rawBody` property.
To do that, create the file `src/api/middlewares.ts` with the following content:
To do this, create the file `src/api/middlewares.ts` with the following content:
```ts title="src/api/middlewares.ts" highlights={preserveHighlights}
import { defineMiddlewares } from "@medusajs/framework/http"
@@ -8219,7 +8219,7 @@ export default defineMiddlewares({
})
```
The middleware route object passed to `routes` accepts a `bodyParser` property whose value is an object of configuration for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
The middleware route object passed to `routes` accepts a `bodyParser` property, whose value is a configuration object for the default body parser. By enabling the `preserveRawBody` property, the raw body data is preserved and stored in the `req.rawBody` property.
Learn more about [middlewares](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md).
@@ -8262,22 +8262,30 @@ export default defineMiddlewares({
The `sizeLimit` property accepts one of the following types of values:
- A string representing the size limit in bytes (For example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
- A string representing the size limit (for example, `100kb`, `2mb`, `5gb`). It is passed to the [bytes](https://www.npmjs.com/package/bytes) library to parse the size.
- A number representing the size limit in bytes. For example, `1024` for 1kb.
### Overriding Request Body Size Limit
You can't override the request body size limit for existing routes, such as Medusa's Store and Admin API routes, due to how [middlewares are applied](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares#how-are-middlewares-ordered-and-applied/index.html.md).
If you need to override the request body size limit for a specific route, you can create a custom [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md) that executes the same functionality as the original route, but with the body size limit you need.
Learn more in the [Override API Routes](https://docs.medusajs.com/learn/fundamentals/api-routes/override/index.html.md) chapter.
***
## Configure File Uploads
To accept file uploads in your API routes, you can configure the [Express Multer middleware](https://expressjs.com/en/resources/middleware/multer.html) on your route.
The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better typing support, install the `@types/multer` package as a development dependency:
The `multer` package is available through the `@medusajs/medusa` package, so you don't need to install it. However, for better TypeScript support, install the `@types/multer` package as a development dependency:
```bash npm2yarn
npm install --save-dev @types/multer
```
Then, to configure file upload for your route, create the file `src/api/middlewares.ts` with the following content:
Then, to configure file uploads for your route, create the file `src/api/middlewares.ts` with the following content:
```ts title="src/api/middlewares.ts" highlights={uploadHighlights}
import { defineMiddlewares } from "@medusajs/framework/http"
@@ -8299,29 +8307,12 @@ export default defineMiddlewares({
})
```
In the example above, you configure the `multer` middleware to store the uploaded files in memory. Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
In the example above, you configure the `multer` middleware to store the uploaded files in memory.
Then, you apply the `upload.array("files")` middleware to the route to accept file uploads. By using the `array` method, you accept multiple file uploads with the same `files` field name.
You can then access the uploaded files in your API route handler:
```ts title="src/api/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
) {
const files = req.files as Express.Multer.File[]
// TODO handle files
}
```
The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
### Uploading Files using File Module Provider
The recommended way to upload the files to storage using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md) is to use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md):
```ts title="src/api/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { MedusaError } from "@medusajs/framework/utils"
@@ -8355,7 +8346,33 @@ export async function POST(
}
```
Check out the [uploadFilesWorkflow reference](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md) for details on the expected input and output of the workflow.
The uploaded files are stored in the `req.files` property as an array of Multer file objects that have properties like `filename` and `mimetype`.
To upload the files, you can use the [uploadFilesWorkflow](https://docs.medusajs.com/resources/references/medusa-workflows/uploadFilesWorkflow/index.html.md), which uploads the files using the configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/index.html.md).
### Test API Route
To test the API route, send a `POST` request to the `/custom` endpoint with the `files` field containing one or more files:
```bash
curl -X POST 'localhost:9000/custom' \
--form 'files=@"/path/to/file.png"'
```
Where `/path/to/file.png` is the path to the file you want to upload.
The request will return a JSON response with the uploaded file information:
```json title="Example Response"
{
"files": [
{
"id": "file_1",
"url": "https://example.com/files/file_1"
}
]
}
```
# Protected API Routes