docs: updates for breaking changes (#9558)

- Update modules registration - Update `medusa-config.js` to `medusa-config.ts` - Update the out directory in the admin deployment guide - Update logger imports - Other fixes Note: will need to re-generate references afterwards Closes #9548
2024-10-14 10:40:30 +00:00
1 parent 2a9fc0e514
commit b6df24463d
@@ -20,7 +20,7 @@ These configurations accept a URL pattern to identify allowed origins.

 For example:

-```js title="medusa-config.js"
+```js title="medusa-config.ts"
 module.exports = defineConfig({
  projectConfig: {
    http: {
@@ -78,7 +78,7 @@ You can do that in the exported middlewares configurations in `src/api/middlewar

 For example:

-export const highlights = [["25", "parseCorsOrigins", "A utility function that parses the CORS configurations in `medusa-config.js`"]]
+export const highlights = [["25", "parseCorsOrigins", "A utility function that parses the CORS configurations in `medusa-config.ts`"]]

 ```ts title="src/api/middlewares.ts" highlights={highlights} collapsibleLines="1-10" expandButtonLabel="Show Imports"
 import { defineMiddlewares } from "@medusajs/medusa"
@@ -117,4 +117,4 @@ export default defineMiddlewares({
 })
 ```

-This retrieves the configurations exported from `medusa-config.js` and applies the `storeCors` to routes starting with `/custom`.
+This retrieves the configurations exported from `medusa-config.ts` and applies the `storeCors` to routes starting with `/custom`.
@@ -27,7 +27,7 @@ A service's constructor accepts as a first parameter an object used to resolve r
 For example:

 ```ts highlights={[["4"], ["10"]]}
-import { Logger } from "@medusajs/medusa"
+import { Logger } from "@medusajs/framework/types"

 type InjectedDependencies = {
  logger: Logger
@@ -56,12 +56,14 @@ For example:
 import {
  LoaderOptions,
 } from "@medusajs/framework/modules-sdk"
-import { Logger } from "@medusajs/medusa"
+import { 
+  ContainerRegistrationKeys
+} from "@medusajs/framework/utils"

 export default async function helloWorldLoader({
  container,
 }: LoaderOptions) {
-  const logger: Logger = container.resolve("logger")
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)

  logger.info("[helloWorldLoader]: Hello, World!")
 }
@@ -100,7 +100,7 @@ export class ClientService {

 Your internal service can't access the module's options.

-To retrieve the module's options, use the `configModule` registered in the module's container, which is the configurations in `medusa-config.js`.
+To retrieve the module's options, use the `configModule` registered in the module's container, which is the configurations in `medusa-config.ts`.

 For example:

@@ -16,21 +16,21 @@ For example, if you’re creating a module that integrates a third-party service

 ## How to Pass Options to a Module?

-To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.js`.
+To pass options to a module, add an `options` property to the module’s configuration in `medusa-config.ts`.

 For example:

-```js title="medusa-config.js"
+```js title="medusa-config.ts"
 module.exports = defineConfig({
  // ...
-  modules: {
-    helloModuleService: {
+  modules: [
+    {
      resolve: "./modules/hello",
      options: {
        capitalize: true,
      },
    },
-  },
+  ]
 })
 ```

@@ -118,37 +118,29 @@ export default Module(HELLO_MODULE, {

 You use the `Module` function imported from `@medusajs/framework/utils` to create the module's definition. It accepts two parameters:

-1. The module's name.
+1. The name that the module's main service is registered under (`helloModuleService`).
 2. An object with a required property `service` indicating the module's main service.

 ### 4. Add Module to Configurations

 The last step is to add the module in Medusa’s configurations.

-In `medusa-config.js`, add a `modules` property and pass to it your custom module:
+In `medusa-config.ts`, add a `modules` property and pass in it your custom module:

-```js title="medusa-config.js" highlights={[["6", "helloModuleService", "The key of the main service to be registered in the Medusa container."]]}
+```ts title="medusa-config.ts" highlights={[["6", "helloModuleService", "The key of the main service to be registered in the Medusa container."]]}
 module.exports = defineConfig({
  projectConfig: {
    // ...
  },
-  modules: {
-    helloModuleService: {
+  modules: [
+    {
      resolve: "./modules/hello",
-    },
-  },
+    }
+  ]
 })
 ```

-The key `helloModuleService` is the name of the module’s main service. It will be registered in the Medusa container with that name.
-
-<Note>
-
-The key must be the same value passed as the first parameter to the `Module` function in the module's definition.
-
-</Note>
-
-Its value is an object having the `resolve` property, whose value is either a path to module's directory relative to `src` (it shouldn't include `src` in the path), or an `npm` package’s name.
+Its value is an array of objects, each having a `resolve` property, whose value is either a path to module's directory relative to `src` (it shouldn't include `src` in the path), or an `npm` package’s name.

 ### 5. Generate Migrations

@@ -18,6 +18,6 @@ This directory is the central place for your custom development. It includes the
 - `subscribers`: Holds your event listeners that are executed asynchronously whenever an event is emitted.
 - `workflows`: Holds your custom flows that can be executed from anywhere in your application.

-## medusa-config.js
+## medusa-config.ts

 This file holds your Medusa configurations, such as your PostgreSQL database configurations.
@@ -97,16 +97,16 @@ Learn more about modules and services [in this guide](../../../basics/modules/pa

 ## 5. Register Module in Config

-Finally, add the module to Medusa's configurations in `medusa-config.js`:
+Finally, add the module to Medusa's configurations in `medusa-config.ts`:

-```js title="medusa-config.js"
+```ts title="medusa-config.ts"
 module.exports = defineConfig({
  // ...
-  modules: {
-    brandModuleService: {
+  modules: [
+    {
      resolve: "./modules/brand",
-    },
-  },
+    }
+  ]
 })
 ```

@@ -61,7 +61,7 @@ export class BrandClient {

 This creates a `BrandClient` service. Using dependency injection, you resolve the `logger` and `configModule` from the Module's container.

-`logger` is useful to log messages, and `configModule` has configurations exported in `medusa-config.js`.
+`logger` is useful to log messages, and `configModule` has configurations exported in `medusa-config.ts`.

 You also define an `options_` property in your service to store the module's options.

@@ -180,19 +180,19 @@ In the main module service, you first resolve through dependency injection the `

 ## 4. Pass Options to the Module

-To pass options in the module, change its configurations in `medusa-config.js`:
+To pass options in the module, change its configurations in `medusa-config.ts`:

-```js title="medusa-config.js"
+```ts title="medusa-config.ts"
 module.exports = defineConfig({
  // ...
-  modules: {
-    brandModuleService: {
+  modules: [
+    {
      resolve: "./modules/brand",
      options: {
        apiKey: process.env.BRAND_API_KEY || "temp",
      },
    },
-  },
+  ] 
 })
 ```

@@ -44,14 +44,13 @@ Also, install the dependencies relevant for the exporter you use. If you're usin
 npm install @opentelemetry/exporter-zipkin
 ```

-### Add instrumentation.js
+### Add instrumentation.ts

-Next, create the file `instrumentation.js` with the following content:
+Next, create the file `instrumentation.ts` with the following content:

-```js title="instrumentation.js"
-const { registerOtel } = require("@medusajs/medusa")
-// If using an exporter other than Zipkin, require it here.
-const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin")
+```ts title="instrumentation.ts"
+import { registerOtel } from "@medusajs/medusa"
+import { ZipkinExporter } from "@opentelemetry/exporter-zipkin"

 // If using an exporter other than Zipkin, initialize it here.
 const exporter = new ZipkinExporter({
@@ -72,7 +71,7 @@ export function register() {
 }
 ```

-In the `instrumentation.js` file, you export a `register` function that uses Medusa's `registerOtel` utility function.
+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.

@@ -26,13 +26,13 @@ export const highlights = [
 ]

 ```ts title="src/jobs/log-message.ts" highlights={highlights}
-import { Logger } from "@medusajs/medusa"
 import { MedusaContainer } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

 export default async function myCustomJob(
  container: MedusaContainer
 ) {
-  const logger: Logger = container.resolve("logger")
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)

  logger.info("I'm using the logger!")
 }
@@ -129,11 +129,14 @@ The `Logger` class has an `activity` method used to log a message of level `info

 For example:

-```ts title="src/loaders/log-message.ts"
-import { Logger, MedusaContainer } from "@medusajs/medusa"
+```ts title="src/jobs/log-message.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

-export default async (container: MedusaContainer) => {
-  const logger = container.resolve<Logger>("logger")
+export default async function myCustomJob(
+  container: MedusaContainer
+) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)

  const activityId = logger.activity("First log message")

@@ -141,7 +144,6 @@ export default async (container: MedusaContainer) => {

  logger.success(activityId, "Last log message")
 }
-
 ```

 The `activity` method returns the ID of the started activity. This ID can then be passed to one of the following methods of the `Logger` class: