From f4b3528fb15abbf5cb1f4b948442acf40ae41b90 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 16 Jun 2025 17:38:45 +0300 Subject: [PATCH] docs: add a section on heavy operations in loaders (#12749) --- .../fundamentals/modules/loaders/page.mdx | 15 +++++++++++++ www/apps/book/generated/edit-dates.mjs | 2 +- www/apps/book/public/llms-full.txt | 21 ++++++++++++++++--- 3 files changed, 34 insertions(+), 4 deletions(-) diff --git a/www/apps/book/app/learn/fundamentals/modules/loaders/page.mdx b/www/apps/book/app/learn/fundamentals/modules/loaders/page.mdx index 265bb1e0fc..8a7bc8373f 100644 --- a/www/apps/book/app/learn/fundamentals/modules/loaders/page.mdx +++ b/www/apps/book/app/learn/fundamentals/modules/loaders/page.mdx @@ -116,6 +116,21 @@ Loaders are also executed when you run [migrations](../../data-models/write-migr --- +## Avoid Heavy Operations in Loaders + +Since loaders are executed when the Medusa application starts, heavy operations will increase the startup time of the application. + +So, avoid operations that take a long time to complete, such as fetching a large amount of data from an external API or database, in loaders. + +### Alternative Solutions + +Instead of performing heavy operations in loaders, consider one of the following solutions: + +- Use a [scheduled job](../../scheduled-jobs/page.mdx) to perform the operation at specified intervals. This way, the operation is performed asynchronously and doesn't block the application startup. +- [Emit custom events](../../events-and-subscribers/emit-event/page.mdx) in an [API route](../../api-routes/page.mdx), then handle the event in a [subscriber](../../events-and-subscribers/page.mdx) to perform the operation asynchronously. You can then send a request to the API route to trigger the operation when needed. + +--- + ## Example: Register Custom MongoDB Connection As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index cca7b39c58..b101e01a12 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -18,7 +18,7 @@ export const generatedEditDates = { "app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-05-16T13:40:16.111Z", "app/learn/fundamentals/modules/container/page.mdx": "2025-05-21T15:07:12.059Z", "app/learn/fundamentals/workflows/execute-another-workflow/page.mdx": "2024-12-09T15:56:22.895Z", - "app/learn/fundamentals/modules/loaders/page.mdx": "2025-05-21T15:15:35.271Z", + "app/learn/fundamentals/modules/loaders/page.mdx": "2025-06-16T13:34:16.462Z", "app/learn/fundamentals/admin/widgets/page.mdx": "2024-12-09T16:43:24.260Z", "app/learn/fundamentals/data-models/page.mdx": "2025-03-18T07:55:56.252Z", "app/learn/fundamentals/modules/remote-link/page.mdx": "2024-09-30T08:43:53.127Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 2c619126b9..027ebf4dbd 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -1136,7 +1136,7 @@ You define the middlewares using the `defineMiddlewares` function and export its In the middleware object, you define three properties: -- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. You pass the create brand's route `/admin/brand`. +- `matcher`: a string or regular expression indicating the API route path to apply the middleware on. You pass the create brand's route `/admin/brands`. - `method`: The HTTP method to restrict the middleware to, which is `POST`. - `middlewares`: An array of middlewares to apply on the route. You pass the `validateAndTransformBody` middleware, passing it the Zod schema you created earlier. @@ -3397,12 +3397,12 @@ export function register() { In the `instrumentation.ts` file, you export a `register` function that uses Medusa's `registerOtel` utility function. You also initialize an instance of the exporter, such as Zipkin, and pass it to the `registerOtel` function. -`registerOtel` accepts an object where you can pass any [NodeSDKConfiguration](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk_node.NodeSDKConfiguration.html) property along with the following properties: +`registerOtel` accepts an object where you can pass any [NodeSDKConfiguration](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_sdk-node.NodeSDKConfiguration.html) property along with the following properties: The `NodeSDKConfiguration` properties are accepted since Medusa v2.5.1. - serviceName: (\`string\`) The name of the service traced. -- exporter: (\[SpanExporter]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_sdk\_trace\_base.SpanExporter.html)) An instance of an exporter, such as Zipkin. +- exporter: (\[SpanExporter]\(https://open-telemetry.github.io/opentelemetry-js/interfaces/\_opentelemetry\_sdk-node.node.SpanExporter.html)) An instance of an exporter, such as Zipkin. - instrument: (\`object\`) Options specifying what to trace. - http: (\`boolean\`) Whether to trace HTTP requests. @@ -14234,6 +14234,21 @@ Loaders are also executed when you run [migrations](https://docs.medusajs.com/le *** +## Avoid Heavy Operations in Loaders + +Since loaders are executed when the Medusa application starts, heavy operations will increase the startup time of the application. + +So, avoid operations that take a long time to complete, such as fetching a large amount of data from an external API or database, in loaders. + +### Alternative Solutions + +Instead of performing heavy operations in loaders, consider one of the following solutions: + +- Use a [scheduled job](https://docs.medusajs.com/learn/fundamentals/scheduled-jobs/index.html.md) to perform the operation at specified intervals. This way, the operation is performed asynchronously and doesn't block the application startup. +- [Emit custom events](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/emit-event/index.html.md) in an [API route](https://docs.medusajs.com/learn/fundamentals/api-routes/index.html.md), then handle the event in a [subscriber](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers/index.html.md) to perform the operation asynchronously. You can then send a request to the API route to trigger the operation when needed. + +*** + ## Example: Register Custom MongoDB Connection As mentioned in this chapter's introduction, loaders are most useful when you need to register a custom resource in the module's container to re-use it in other customizations in the module.