Module Options

In this chapter, you’ll learn about passing options to your module from the Medusa application’s configurations and using them in the module’s resources.

What are Module Options?#

A module can receive options to customize or configure its functionality. For example, if you’re creating a module that integrates a third-party service, you’ll want to receive the integration credentials in the options rather than adding them directly in your code.

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.ts.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "./src/modules/hello",6      options: {7        capitalize: true,8      },9    },10  ],11})

The options property’s value is an object. You can pass any properties you want.

Pass Options to a Module in a Plugin#

If your module is part of a plugin, you can pass options to the module in the plugin’s configuration.

For example:

medusa-config.ts
1import { defineConfig } from "@medusajs/framework/utils"2module.exports = defineConfig({3  plugins: [4    {5      resolve: "@myorg/plugin-name",6      options: {7        capitalize: true,8      },9    },10  ],11})

The options property in the plugin configuration is passed to all modules in a plugin.

Access Module Options in Main Service#

The module’s main service receives the module options as a second parameter.

For example:

src/modules/hello/service.ts
1import { MedusaService } from "@medusajs/framework/utils"2import MyCustom from "./models/my-custom"3
4// recommended to define type in another file5type ModuleOptions = {6  capitalize?: boolean7}8
9export default class HelloModuleService extends MedusaService({10  MyCustom,11}){12  protected options_: ModuleOptions13
14  constructor({}, options?: ModuleOptions) {15    super(...arguments)16
17    this.options_ = options || {18      capitalize: false,19    }20  }21
22  // ...23}

Access Module Options in Loader#

The object that a module’s loaders receive as a parameter has an options property holding the module's options.

For example:

src/modules/hello/loaders/hello-world.ts
1import {2  LoaderOptions,3} from "@medusajs/framework/types"4
5// recommended to define type in another file6type ModuleOptions = {7  capitalize?: boolean8}9
10export default async function helloWorldLoader({11  options,12}: LoaderOptions<ModuleOptions>) {13  14  console.log(15    "[HELLO MODULE] Just started the Medusa application!",16    options17  )18}

Validate Module Options#

If you expect a certain option and want to throw an error if it's not provided or isn't valid, it's recommended to perform the validation in a loader. The module's service is only instantiated when it's used, whereas the loader runs the when the Medusa application starts.

So, by performing the validation in the loader, you ensure you can throw an error at an early point, rather than when the module is used.

For example, to validate that the Hello Module received an apiKey option, create the loader src/modules/loaders/validate.ts:

src/modules/hello/loaders/validate.ts
1import { LoaderOptions } from "@medusajs/framework/types"2import { MedusaError } from "@medusajs/framework/utils"3
4// recommended to define type in another file5type ModuleOptions = {6  apiKey?: string7}8
9export default async function validationLoader({10  options,11}: LoaderOptions<ModuleOptions>) {12  if (!options.apiKey) {13    throw new MedusaError(14      MedusaError.Types.INVALID_DATA,15      "Hello Module requires an apiKey option."16    )17  }18}

Then, export the loader in the module's definition file, as explained in this chapter:

src/modules/hello/index.ts
1// other imports...2import validationLoader from "./loaders/validate"3
4export default Module("hello", {5  // ...6  loaders: [validationLoader],7})

Now, when the Medusa application starts, the loader will run, validating the module's options and throwing an error if the apiKey option is missing.