From 541bff8c9b34b1b4e5d49cfdfbf4ef7b95ca8dde Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 14 Jul 2025 14:17:25 +0300 Subject: [PATCH] docs: changes for new releases + fixes (#12945) * docs: changes for new releases + fixes * remove container option --- .../configurations/medusa-config/page.mdx | 81 +++++++++++++++++++ .../api-routes/retrieve-custom-links/page.mdx | 11 ++- .../workflows/long-running-workflow/page.mdx | 20 ----- www/apps/book/generated/edit-dates.mjs | 6 +- www/apps/book/public/llms-full.txt | 66 +++++++++------ .../resources/app/create-medusa-app/page.mdx | 29 +++++++ .../restock-notification/page.mdx | 3 +- .../examples/restaurant-delivery/page.mdx | 14 +--- www/apps/resources/generated/edit-dates.mjs | 6 +- .../CodeBlock/Collapsible/Button/index.tsx | 4 +- 10 files changed, 175 insertions(+), 65 deletions(-) diff --git a/www/apps/book/app/learn/configurations/medusa-config/page.mdx b/www/apps/book/app/learn/configurations/medusa-config/page.mdx index bd7f12251b..6336f12997 100644 --- a/www/apps/book/app/learn/configurations/medusa-config/page.mdx +++ b/www/apps/book/app/learn/configurations/medusa-config/page.mdx @@ -70,6 +70,87 @@ module.exports = defineConfig({ The `projectConfig` object contains essential configurations related to the Medusa application, such as database and CORS configurations. +### cookieOptions + + + +This option is available since Medusa [v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5). + + + +The `projectConfig.cookieOptions` configuration defines cookie options to be passed to `express-session` when creating the session cookie. This configuration is useful when simulating a production environment locally, where you may need to set options like `secure` or `sameSite`. + +#### Example + +```ts title="medusa-config.ts" +module.exports = defineConfig({ + projectConfig: { + cookieOptions: { + sameSite: "lax", + }, + // ... + }, + // ... +}) +``` + +#### Properties + +Aside from the following options, you can pass any property that the [express-session's cookie option accepts](https://www.npmjs.com/package/express-session). + + + ### databaseDriverOptions The `projectConfig.databaseDriverOptions` configuration is an object of additional options used to configure the PostgreSQL connection. For example, you can support TLS/SSL connection using this configuration's `ssl` property. diff --git a/www/apps/book/app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx b/www/apps/book/app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx index e6c9518e8e..f1ed1bdad2 100644 --- a/www/apps/book/app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx +++ b/www/apps/book/app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx @@ -45,7 +45,7 @@ The API routes that restrict the fields and relations you can retrieve are: ### How to Override Allowed Fields and Relations -For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](../middlewares/page.mdx) to those routes. +For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by applying a [global middleware](../middlewares/page.mdx) to those routes. For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](!api!/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content: @@ -66,10 +66,9 @@ export default defineMiddlewares({ routes: [ { matcher: "/store/customers/me", - method: "GET", middlewares: [ (req, res, next) => { - req.allowed?.push("b2b_company") + (req.allowed ??= []).push("b2b_company") next() }, ], @@ -90,3 +89,9 @@ curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \ ``` In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter. + + + +This approach only works using a global middleware. It doesn't work in a route middleware. + + \ No newline at end of file diff --git a/www/apps/book/app/learn/fundamentals/workflows/long-running-workflow/page.mdx b/www/apps/book/app/learn/fundamentals/workflows/long-running-workflow/page.mdx index 1b285d904b..ab1577a880 100644 --- a/www/apps/book/app/learn/fundamentals/workflows/long-running-workflow/page.mdx +++ b/www/apps/book/app/learn/fundamentals/workflows/long-running-workflow/page.mdx @@ -151,9 +151,6 @@ export const setStepSuccessStep = createStep( workflowId: "hello-world", }, stepResponse: new StepResponse("Done!"), - options: { - container, - }, }) } ) @@ -203,20 +200,6 @@ The `setStepSuccess` method of the workflow engine's main service accepts as a p description: "Set the response of the step. This is similar to the response you return in a step's definition, but since the `async` step doesn't have a response, you set its response when changing its status.", optional: false }, - { - name: "options", - type: "`Record`", - description: "Options to pass to the step.", - optional: true, - children: [ - { - name: "container", - type: "`MedusaContainer`", - description: "An instance of the Medusa Container", - optional: true - } - ] - } ]} /> @@ -269,9 +252,6 @@ export const setStepFailureStep = createStep( workflowId: "hello-world", }, stepResponse: new StepResponse("Failed!"), - options: { - container, - }, }) } ) diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index e522a42138..bb9d790602 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -30,7 +30,7 @@ export const generatedEditDates = { "app/learn/fundamentals/workflows/conditions/page.mdx": "2025-01-27T08:45:19.027Z", "app/learn/fundamentals/modules/module-link-directions/page.mdx": "2024-07-24T09:16:01+02:00", "app/learn/fundamentals/admin/page.mdx": "2025-04-18T10:28:47.328Z", - "app/learn/fundamentals/workflows/long-running-workflow/page.mdx": "2025-03-28T07:02:34.467Z", + "app/learn/fundamentals/workflows/long-running-workflow/page.mdx": "2025-07-14T10:32:21.640Z", "app/learn/fundamentals/workflows/constructor-constraints/page.mdx": "2025-04-24T13:18:24.184Z", "app/learn/fundamentals/data-models/write-migration/page.mdx": "2025-03-24T06:41:48.915Z", "app/learn/fundamentals/data-models/manage-relationships/page.mdx": "2025-04-25T14:16:41.124Z", @@ -112,13 +112,13 @@ export const generatedEditDates = { "app/learn/resources/contribution-guidelines/admin-translations/page.mdx": "2025-02-11T16:57:46.726Z", "app/learn/resources/contribution-guidelines/docs/page.mdx": "2025-05-26T15:55:02.974Z", "app/learn/resources/usage/page.mdx": "2025-02-26T13:35:34.824Z", - "app/learn/configurations/medusa-config/page.mdx": "2025-06-10T13:18:26.064Z", + "app/learn/configurations/medusa-config/page.mdx": "2025-07-14T09:28:54.302Z", "app/learn/configurations/ts-aliases/page.mdx": "2025-02-11T16:57:46.683Z", "app/learn/production/worker-mode/page.mdx": "2025-03-11T15:21:50.906Z", "app/learn/fundamentals/module-links/read-only/page.mdx": "2025-05-13T15:04:12.107Z", "app/learn/fundamentals/data-models/properties/page.mdx": "2025-03-18T07:57:17.826Z", "app/learn/fundamentals/framework/page.mdx": "2025-06-26T14:26:22.120Z", - "app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx": "2025-04-25T14:26:25.000Z", + "app/learn/fundamentals/api-routes/retrieve-custom-links/page.mdx": "2025-07-14T10:24:32.582Z", "app/learn/fundamentals/workflows/errors/page.mdx": "2025-04-25T14:26:25.000Z", "app/learn/fundamentals/api-routes/override/page.mdx": "2025-05-09T08:01:24.493Z", "app/learn/fundamentals/module-links/index/page.mdx": "2025-05-23T07:57:58.958Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index baccd30e18..7e287e01e8 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -140,6 +140,39 @@ module.exports = defineConfig({ The `projectConfig` object contains essential configurations related to the Medusa application, such as database and CORS configurations. +### cookieOptions + +This option is available since Medusa [v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5). + +The `projectConfig.cookieOptions` configuration defines cookie options to be passed to `express-session` when creating the session cookie. This configuration is useful when simulating a production environment locally, where you may need to set options like `secure` or `sameSite`. + +#### Example + +```ts title="medusa-config.ts" +module.exports = defineConfig({ + projectConfig: { + cookieOptions: { + sameSite: "lax", + }, + // ... + }, + // ... +}) +``` + +#### Properties + +Aside from the following options, you can pass any property that the [express-session's cookie option accepts](https://www.npmjs.com/package/express-session). + +- secure: (\`boolean\`) +- sameSite: (\`lax\` | \`strict\` | \`none\`) +- maxAge: (\`number\`) The maximum age of the cookie in milliseconds set in the \`Set-Cookie\` header. +- httpOnly: (\`boolean\`) Whether to set the \`HttpOnly Set-Cookie\` attribute. +- priority: (\`low\` | \`medium\` | \`high\`) The value of the \[Priority Set-Cookie attribute]\(https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1) +- domain: (\`string\`) The value of the \`Domain Set-Cookie\` attribute. By default, no domain is set, and most clients will consider the cookie to apply to the current domain only. +- path: (\`string\`) The value of the \`Path Set-Cookie\` attribute +- signed: (\`boolean\`) Whether to sign the cookie. + ### databaseDriverOptions The `projectConfig.databaseDriverOptions` configuration is an object of additional options used to configure the PostgreSQL connection. For example, you can support TLS/SSL connection using this configuration's `ssl` property. @@ -677,7 +710,7 @@ The value for this configuration can be one of the following: ```ts title="medusa-config.ts" module.exports = defineConfig({ projectConfig: { - workerMode: process.env.WORKER_MODE || "shared", + workerMode: process.env.WORKER_MODE as "shared" | "worker" | "server" || "shared", // ... }, // ... @@ -7619,7 +7652,7 @@ The API routes that restrict the fields and relations you can retrieve are: ### How to Override Allowed Fields and Relations -For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by adding a [middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes. +For these routes, you need to override the allowed fields and relations to be retrieved. You can do this by applying a [global middleware](https://docs.medusajs.com/learn/fundamentals/api-routes/middlewares/index.html.md) to those routes. For example, to allow retrieving the `b2b_company` of a customer using the [Get Customer Admin API Route](https://docs.medusajs.com/api/admin#customers_getcustomersid), create the file `src/api/middlewares.ts` with the following content: @@ -7632,10 +7665,9 @@ export default defineMiddlewares({ routes: [ { matcher: "/store/customers/me", - method: "GET", middlewares: [ (req, res, next) => { - req.allowed?.push("b2b_company") + (req.allowed ??= []).push("b2b_company") next() }, ], @@ -7657,6 +7689,8 @@ curl 'http://localhost:9000/admin/customers/{id}?fields=*b2b_company' \ In this example, you retrieve the `b2b_company` relation of the customer using the `fields` query parameter. +This approach only works using a global middleware. It doesn't work in a route middleware. + # Request Body and Query Parameter Validation @@ -17308,9 +17342,6 @@ export const setStepSuccessStep = createStep( workflowId: "hello-world", }, stepResponse: new StepResponse("Done!"), - options: { - container, - }, }) } ) @@ -17330,9 +17361,6 @@ The `setStepSuccess` method of the workflow engine's main service accepts as a p - workflowId: (\`string\`) The ID of the workflow. This is the first parameter passed to \`createWorkflow\` when creating the workflow. - stepResponse: (\`StepResponse\`) Set the response of the step. This is similar to the response you return in a step's definition, but since the \`async\` step doesn't have a response, you set its response when changing its status. -- options: (\`Record\\`) Options to pass to the step. - - - container: (\`MedusaContainer\`) An instance of the Medusa Container ### Change Step Status to Failed @@ -17374,9 +17402,6 @@ export const setStepFailureStep = createStep( workflowId: "hello-world", }, stepResponse: new StepResponse("Failed!"), - options: { - container, - }, }) } ) @@ -83992,6 +84017,7 @@ export const createRestockSubscriptionWorkflow = createWorkflow( return !customer.email } ).then(() => { + // @ts-ignore const { data } = useQueryGraphStep({ entity: "customer", fields: ["email"], @@ -89892,14 +89918,14 @@ To implement the step, create the file `src/workflows/restaurant/steps/create-re ```ts title="src/workflows/restaurant/steps/create-restaurant.ts" highlights={createRestaurantHighlight} collapsibleLines="1-7" expandMoreLabel="Show Imports" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { - CreateRestaurantDTO, + CreateRestaurant, } from "../../../modules/restaurant/types/mutations" import { RESTAURANT_MODULE } from "../../../modules/restaurant" import RestaurantModuleService from "../../../modules/restaurant/service" export const createRestaurantStep = createStep( "create-restaurant-step", - async function (data: CreateRestaurantDTO, { container }) { + async function (data: CreateRestaurant, { container }) { const restaurantModuleService: RestaurantModuleService = container.resolve( RESTAURANT_MODULE ) @@ -89971,7 +89997,7 @@ Then, create the file `src/api/restaurants/route.ts` with the following content: import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" import { MedusaError } from "@medusajs/framework/utils" import { - CreateRestaurantDTO, + CreateRestaurant, } from "../../modules/restaurant/types/mutations" import { createRestaurantWorkflow, @@ -89979,7 +90005,7 @@ import { import { restaurantSchema } from "./validation-schemas" export async function POST(req: MedusaRequest, res: MedusaResponse) { - const validatedBody = restaurantSchema.parse(req.body) as CreateRestaurantDTO + const validatedBody = restaurantSchema.parse(req.body) as CreateRestaurant if (!validatedBody) { return MedusaError.Types.INVALID_DATA @@ -91663,9 +91689,6 @@ export const setStepSuccessStep = createStep( workflowId: handleDeliveryWorkflowId, }, stepResponse: new StepResponse(updatedDelivery, updatedDelivery.id), - options: { - container, - }, }) } ) @@ -91710,9 +91733,6 @@ export const setStepFailedStep = createStep( workflowId: handleDeliveryWorkflowId, }, stepResponse: new StepResponse(updatedDelivery, updatedDelivery.id), - options: { - container, - }, }) } ) diff --git a/www/apps/resources/app/create-medusa-app/page.mdx b/www/apps/resources/app/create-medusa-app/page.mdx index 628bf4f789..5446d351bb 100644 --- a/www/apps/resources/app/create-medusa-app/page.mdx +++ b/www/apps/resources/app/create-medusa-app/page.mdx @@ -223,6 +223,23 @@ npx create-medusa-app@latest [project-name] + + + + `--version` + + + + + Specify the Medusa version to install in the project. The specified version will be used for every `@medusajs/*` package in the Medusa and Next.js Starter projects. + + + + + The latest version of Medusa at the time of running the command. + + + @@ -270,6 +287,18 @@ Learn more about how to create a plugin in [this documentation](!docs!/learn/fun --- +## Install a Specific Medusa Version + +To install a specific version of Medusa, use the `--version` option. This will install the specified version for every `@medusajs/*` package in the Medusa and Next.js Starter projects. For example: + +```bash +npx create-medusa-app@latest my-medusa-store --version 2.3.0 +``` + +This will create a new Medusa project with the `2.3.0` version. + +--- + ## Troubleshooting { + // @ts-ignore const { data } = useQueryGraphStep({ entity: "customer", fields: ["email"], diff --git a/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx b/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx index 29fb52df46..289031c6df 100644 --- a/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx +++ b/www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx @@ -519,14 +519,14 @@ export const createRestaurantHighlight = [ ```ts title="src/workflows/restaurant/steps/create-restaurant.ts" highlights={createRestaurantHighlight} collapsibleLines="1-7" expandMoreLabel="Show Imports" import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk" import { - CreateRestaurantDTO, + CreateRestaurant, } from "../../../modules/restaurant/types/mutations" import { RESTAURANT_MODULE } from "../../../modules/restaurant" import RestaurantModuleService from "../../../modules/restaurant/service" export const createRestaurantStep = createStep( "create-restaurant-step", - async function (data: CreateRestaurantDTO, { container }) { + async function (data: CreateRestaurant, { container }) { const restaurantModuleService: RestaurantModuleService = container.resolve( RESTAURANT_MODULE ) @@ -602,7 +602,7 @@ export const createRestaurantRouteHighlights = [ import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http" import { MedusaError } from "@medusajs/framework/utils" import { - CreateRestaurantDTO, + CreateRestaurant, } from "../../modules/restaurant/types/mutations" import { createRestaurantWorkflow, @@ -610,7 +610,7 @@ import { import { restaurantSchema } from "./validation-schemas" export async function POST(req: MedusaRequest, res: MedusaResponse) { - const validatedBody = restaurantSchema.parse(req.body) as CreateRestaurantDTO + const validatedBody = restaurantSchema.parse(req.body) as CreateRestaurant if (!validatedBody) { return MedusaError.Types.INVALID_DATA @@ -2449,9 +2449,6 @@ export const setStepSuccessStep = createStep( workflowId: handleDeliveryWorkflowId, }, stepResponse: new StepResponse(updatedDelivery, updatedDelivery.id), - options: { - container, - }, }) } ) @@ -2500,9 +2497,6 @@ export const setStepFailedStep = createStep( workflowId: handleDeliveryWorkflowId, }, stepResponse: new StepResponse(updatedDelivery, updatedDelivery.id), - options: { - container, - }, }) } ) diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 2a88b7298f..c69106a655 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -99,7 +99,7 @@ export const generatedEditDates = { "app/commerce-modules/user/user-creation-flows/page.mdx": "2025-02-26T11:35:54.685Z", "app/commerce-modules/user/page.mdx": "2025-04-17T08:48:17.980Z", "app/commerce-modules/page.mdx": "2025-04-17T08:48:34.855Z", - "app/create-medusa-app/page.mdx": "2025-01-16T10:00:25.975Z", + "app/create-medusa-app/page.mdx": "2025-07-14T08:51:06.654Z", "app/deployment/admin/vercel/page.mdx": "2024-10-16T08:10:29.377Z", "app/deployment/medusa-application/railway/page.mdx": "2025-04-17T08:28:58.981Z", "app/deployment/storefront/vercel/page.mdx": "2025-05-20T07:51:40.712Z", @@ -569,7 +569,7 @@ export const generatedEditDates = { "app/medusa-cli/commands/start/page.mdx": "2025-04-08T11:56:15.522Z", "app/medusa-cli/commands/telemtry/page.mdx": "2025-01-16T09:51:24.323Z", "app/medusa-cli/commands/user/page.mdx": "2024-08-28T10:44:52.489Z", - "app/recipes/marketplace/examples/restaurant-delivery/page.mdx": "2025-05-20T07:51:40.721Z", + "app/recipes/marketplace/examples/restaurant-delivery/page.mdx": "2025-07-14T10:32:58.301Z", "references/types/HttpTypes/interfaces/types.HttpTypes.AdminCreateCustomerGroup/page.mdx": "2024-12-09T13:21:33.569Z", "references/types/HttpTypes/interfaces/types.HttpTypes.AdminCreateReservation/page.mdx": "2025-04-11T09:04:47.498Z", "references/types/HttpTypes/interfaces/types.HttpTypes.AdminCustomerGroup/page.mdx": "2025-05-20T07:51:41.059Z", @@ -5565,7 +5565,7 @@ export const generatedEditDates = { "references/modules/sales_channel_models/page.mdx": "2024-12-10T14:55:13.205Z", "references/types/DmlTypes/types/types.DmlTypes.KnownDataTypes/page.mdx": "2024-12-17T16:57:19.922Z", "references/types/DmlTypes/types/types.DmlTypes.RelationshipTypes/page.mdx": "2024-12-10T14:54:55.435Z", - "app/recipes/commerce-automation/restock-notification/page.mdx": "2025-06-26T12:40:40.542Z", + "app/recipes/commerce-automation/restock-notification/page.mdx": "2025-07-14T09:35:35.226Z", "app/integrations/guides/shipstation/page.mdx": "2025-05-20T07:51:40.717Z", "app/nextjs-starter/guides/customize-stripe/page.mdx": "2025-05-20T07:51:40.717Z", "references/core_flows/Cart/Workflows_Cart/functions/core_flows.Cart.Workflows_Cart.listShippingOptionsForCartWithPricingWorkflow/page.mdx": "2025-06-25T10:11:28.364Z", diff --git a/www/packages/docs-ui/src/components/CodeBlock/Collapsible/Button/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/Collapsible/Button/index.tsx index 7d56b49a45..337dd35a95 100644 --- a/www/packages/docs-ui/src/components/CodeBlock/Collapsible/Button/index.tsx +++ b/www/packages/docs-ui/src/components/CodeBlock/Collapsible/Button/index.tsx @@ -27,7 +27,7 @@ export const CodeBlockCollapsibleButton = ({ {type === "start" && (