docs: add a section on heavy operations in loaders (medusajs#12749)

Author: shahednasser

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.

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",

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.