diff --git a/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx b/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx
index 679ea170f6..d36e3aa6c4 100644
--- a/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx
@@ -65,10 +65,16 @@ If you receive a type error on `import.meta.env`, create the file `src/admin/vit
```ts title="src/admin/vite-env.d.ts"
///
+
+declare const __BASE__: string
+declare const __BACKEND_URL__: string
+declare const __STOREFRONT_URL__: string
```
This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
+Note that the `__BASE__`, `__BACKEND_URL__`, and `__STOREFRONT_URL__` variables are global variables available in your admin customizations. Learn more in the [Tips for Admin Customizations](../tips/page.mdx#global-variables-in-admin-customizations) chapter.
+
---
## Check Node Environment in Admin Customizations
@@ -122,3 +128,13 @@ export const config = defineWidgetConfig({
export default ProductWidget
```
+
+To fix possible type errors, create the file `src/admin/vite-env.d.ts` and add the global variables:
+
+```ts title="src/admin/vite-env.d.ts"
+///
+
+declare const __BACKEND_URL__: string
+declare const __BASE__: string
+declare const __STOREFRONT_URL__: string
+```
\ No newline at end of file
diff --git a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx b/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx
index 4abca34b99..b0e4f8e00d 100644
--- a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx
@@ -170,6 +170,16 @@ In your admin customizations, you can use the following global variables:
- `__BACKEND_URL__`: The URL to the Medusa backend, as set in the [admin.backendUrl](../../../configurations/medusa-config/page.mdx#backendurl) configuration in `medusa-config.ts`.
- `__STOREFRONT_URL__`: The URL to the storefront, as set in the [admin.storefrontUrl](../../../configurations/medusa-config/page.mdx#storefrontUrl) configuration in `medusa-config.ts`.
+If you get type errors while using these variables, you can create the file `src/admin/vite-env.d.ts` with the following content:
+
+```ts title="src/admin/vite-env.d.ts"
+///
+
+declare const __BASE__: string
+declare const __BACKEND_URL__: string
+declare const __STOREFRONT_URL__: string
+```
+
---
## Admin Translations
diff --git a/www/apps/book/app/learn/fundamentals/workflows/constructor-constraints/page.mdx b/www/apps/book/app/learn/fundamentals/workflows/constructor-constraints/page.mdx
index 7ce0054ca1..dda65638b3 100644
--- a/www/apps/book/app/learn/fundamentals/workflows/constructor-constraints/page.mdx
+++ b/www/apps/book/app/learn/fundamentals/workflows/constructor-constraints/page.mdx
@@ -333,11 +333,9 @@ Instead, refer to the [Error Handling](../errors/page.mdx) chapter for alternati
---
-## Step Constraints
+## Returned Value Constraints
-### Returned Values
-
-A step must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object.
+Data returned from workflows and steps are serialized, allowing Medusa to store them in the database. So, you must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object, from workflows and steps.
Values of other types, such as Maps, aren't allowed.
@@ -379,4 +377,67 @@ const step1 = createStep(
})
}
)
-```
\ No newline at end of file
+```
+
+### Buffer Example
+
+In some cases, you may need to return a buffer. For example, when your workflow generates a file and you want to return it as a buffer.
+
+In those cases, you can return an object containing the buffer as a property. Then, in customizations that execute the workflow, you can recreate the buffer from the serialized data.
+
+For example, consider the following workflow that returns a buffer:
+
+```ts
+import {
+ createWorkflow,
+ createStep,
+ WorkflowResponse,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+ "step-1",
+ (_, { container }) => {
+ const buffer = Buffer.from("Hello, World!")
+
+ return new StepResponse({
+ buffer,
+ })
+ }
+)
+
+const myWorkflow = createWorkflow(
+ "hello-world",
+ function () {
+ const step1Response = step1()
+
+ return new WorkflowResponse({
+ buffer: step1Response.buffer,
+ })
+ }
+)
+```
+
+Then, in an API route that executes this workflow, you can recreate the buffer from the serialized data using `Buffer.from`:
+
+```ts
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import myWorkflow from "../../workflows/hello-world"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await myWorkflow(req.scope)
+ .run()
+
+ const buffer = Buffer.from(result.buffer)
+
+ res.setHeader("Content-Type", "application/octet-stream")
+ res.setHeader("Content-Disposition", "attachment; filename=hello.txt")
+ res.send(buffer)
+}
+```
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index cf2b51549a..d78904b0d7 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/www/apps/book/generated/edit-dates.mjs
@@ -31,7 +31,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/modules/module-link-directions/page.mdx": "2024-07-24T09:16:01+02:00",
"app/learn/fundamentals/admin/page.mdx": "2025-07-25T12:46:15.466Z",
"app/learn/fundamentals/workflows/long-running-workflow/page.mdx": "2025-08-01T07:16:21.736Z",
- "app/learn/fundamentals/workflows/constructor-constraints/page.mdx": "2025-04-24T13:18:24.184Z",
+ "app/learn/fundamentals/workflows/constructor-constraints/page.mdx": "2025-08-01T13:11:18.823Z",
"app/learn/fundamentals/data-models/write-migration/page.mdx": "2025-07-25T13:53:00.692Z",
"app/learn/fundamentals/data-models/manage-relationships/page.mdx": "2025-04-25T14:16:41.124Z",
"app/learn/fundamentals/modules/remote-query/page.mdx": "2024-07-21T21:20:24+02:00",
@@ -43,7 +43,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2025-07-25T15:54:56.135Z",
"app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-02-14T08:34:03.184Z",
"app/learn/fundamentals/api-routes/http-methods/page.mdx": "2025-07-25T15:12:29.347Z",
- "app/learn/fundamentals/admin/tips/page.mdx": "2025-05-26T14:58:56.390Z",
+ "app/learn/fundamentals/admin/tips/page.mdx": "2025-08-01T13:14:23.246Z",
"app/learn/fundamentals/api-routes/cors/page.mdx": "2025-03-11T08:54:26.281Z",
"app/learn/fundamentals/admin/ui-routes/page.mdx": "2025-07-25T06:58:26.149Z",
"app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-07-18T15:20:25.735Z",
@@ -105,7 +105,7 @@ export const generatedEditDates = {
"app/learn/customization/reuse-customizations/page.mdx": "2025-01-22T10:01:57.665Z",
"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-05-26T15:02:25.624Z",
+ "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/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",
diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index 968cfe30ca..8e1afeda0e 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/www/apps/book/public/llms-full.txt
@@ -6079,10 +6079,16 @@ If you receive a type error on `import.meta.env`, create the file `src/admin/vit
```ts title="src/admin/vite-env.d.ts"
///
+
+declare const __BASE__: string
+declare const __BACKEND_URL__: string
+declare const __STOREFRONT_URL__: string
```
This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
+Note that the `__BASE__`, `__BACKEND_URL__`, and `__STOREFRONT_URL__` variables are global variables available in your admin customizations. Learn more in the [Tips for Admin Customizations](https://docs.medusajs.com/learn/fundamentals/admin/tips#global-variables-in-admin-customizations/index.html.md) chapter.
+
***
## Check Node Environment in Admin Customizations
@@ -6137,6 +6143,16 @@ export const config = defineWidgetConfig({
export default ProductWidget
```
+To fix possible type errors, create the file `src/admin/vite-env.d.ts` and add the global variables:
+
+```ts title="src/admin/vite-env.d.ts"
+///
+
+declare const __BACKEND_URL__: string
+declare const __BASE__: string
+declare const __STOREFRONT_URL__: string
+```
+
# Admin Development
@@ -6485,6 +6501,16 @@ In your admin customizations, you can use the following global variables:
- `__BACKEND_URL__`: The URL to the Medusa backend, as set in the [admin.backendUrl](https://docs.medusajs.com/learn/configurations/medusa-config#backendurl/index.html.md) configuration in `medusa-config.ts`.
- `__STOREFRONT_URL__`: The URL to the storefront, as set in the [admin.storefrontUrl](https://docs.medusajs.com/learn/configurations/medusa-config#storefrontUrl/index.html.md) configuration in `medusa-config.ts`.
+If you get type errors while using these variables, you can create the file `src/admin/vite-env.d.ts` with the following content:
+
+```ts title="src/admin/vite-env.d.ts"
+///
+
+declare const __BASE__: string
+declare const __BACKEND_URL__: string
+declare const __STOREFRONT_URL__: string
+```
+
***
## Admin Translations
@@ -18546,11 +18572,9 @@ Instead, refer to the [Error Handling](https://docs.medusajs.com/learn/fundament
***
-## Step Constraints
+## Returned Value Constraints
-### Returned Values
-
-A step must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object.
+Data returned from workflows and steps are serialized, allowing Medusa to store them in the database. So, you must only return serializable values, such as [primitive values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values) or an object, from workflows and steps.
Values of other types, such as Maps, aren't allowed.
@@ -18594,6 +18618,69 @@ const step1 = createStep(
)
```
+### Buffer Example
+
+In some cases, you may need to return a buffer. For example, when your workflow generates a file and you want to return it as a buffer.
+
+In those cases, you can return an object containing the buffer as a property. Then, in customizations that execute the workflow, you can recreate the buffer from the serialized data.
+
+For example, consider the following workflow that returns a buffer:
+
+```ts
+import {
+ createWorkflow,
+ createStep,
+ WorkflowResponse,
+ StepResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+const step1 = createStep(
+ "step-1",
+ (_, { container }) => {
+ const buffer = Buffer.from("Hello, World!")
+
+ return new StepResponse({
+ buffer,
+ })
+ }
+)
+
+const myWorkflow = createWorkflow(
+ "hello-world",
+ function () {
+ const step1Response = step1()
+
+ return new WorkflowResponse({
+ buffer: step1Response.buffer,
+ })
+ }
+)
+```
+
+Then, in an API route that executes this workflow, you can recreate the buffer from the serialized data using `Buffer.from`:
+
+```ts
+import type {
+ MedusaRequest,
+ MedusaResponse,
+} from "@medusajs/framework/http"
+import myWorkflow from "../../workflows/hello-world"
+
+export async function GET(
+ req: MedusaRequest,
+ res: MedusaResponse
+) {
+ const { result } = await myWorkflow(req.scope)
+ .run()
+
+ const buffer = Buffer.from(result.buffer)
+
+ res.setHeader("Content-Type", "application/octet-stream")
+ res.setHeader("Content-Disposition", "attachment; filename=hello.txt")
+ res.send(buffer)
+}
+```
+
# Error Handling in Workflows