Skip to main content
Skip to main content


The configurations for your Medusa backend are in medusa-config.js located in the root of your Medusa project. The configurations include database, modules, and plugin configurations, among other configurations.

medusa-config.js exports an object having the following properties:

  • projectConfig: (required): An object that holds general configurations related to the Medusa backend, such as database or CORS configurations.
  • plugins: An array of plugin configurations that defines what plugins are installed and optionally specifies each of their configurations.
  • modules: An object that defines what modules are installed and optionally specifies each of their configurations.
  • featureFlags: An object that enables or disables features guarded by a feature flag.

For example:

module.exports = {

Environment Variables

It's highly recommended to store the values of configurations in environment variables, then reference them within medusa-config.js.

During development, you can set your environment variables in the .env file at the root of your Medusa backend project. In production, setting the environment variables depends on the hosting provider.


This property holds essential configurations related to the Medusa backend, such as database and CORS configurations.
plugins(string | object)[]Required
On your Medusa backend, you can use Plugins to add custom features or integrate third-party services. For example, installing a plugin to use Stripe as a payment processor. Aside from installing the plugin with NPM, you need to pass the plugin you installed into the plugins array defined in medusa-config.js. The items in the array can either be:
  • A string, which is the name of the plugin to add. You can pass a plugin as a string if it doesn’t require any configurations.
  • An object having the following properties:
    • resolve: The name of the plugin.
    • options: An object that includes the plugin’s options. These options vary for each plugin, and you should refer to the plugin’s documentation for available options.
featureFlagsRecord<string, string \| boolean>Required
Some features in the Medusa backend are guarded by a feature flag. This ensures constant shipping of new features while maintaining the engine’s stability. You can specify whether a feature should or shouldn’t be used in your backend by enabling its feature flag. Feature flags can be enabled through either environment variables or through this configuration exported in medusa-config.js. If you want to use the environment variables method, learn more about it in the Feature Flags documentation. The featureFlags configuration is an object. Its properties are the names of the feature flags. Each property’s value is a boolean indicating whether the feature flag is enabled. You can find available feature flags and their key name here.
modulesRecord<string, boolean \| Partial&#60;[InternalModuleDeclaration](/references/types/ModulesSdkTypes/types/types.ModulesSdkTypes.InternalModuleDeclaration) \| [ExternalModuleDeclaration](/references/types/ModulesSdkTypes/types/types.ModulesSdkTypes.ExternalModuleDeclaration)&#62;>
In Medusa, commerce and core logic are modularized to allow developers to extend or replace certain modules with custom implementations. Aside from installing the module with NPM, you must add it to the exported object in medusa-config.js. The keys of the modules configuration object refer to the type of module. Its value can be one of the following:
  1. A boolean value indicating whether the module type is enabled;
  2. Or a string value indicating the name of the module to be used for the module type. This can be used if the module does not require any options;
  3. Or an object having the following properties, but typically you would mainly use the resolve and options properties only:
    1. resolve: a string indicating the name of the module.
    2. options: an object indicating the options to pass to the module. These options vary for each module, and you should refer to the module’s documentation for details on them.
    3. resources: a string indicating whether the module shares the dependency container with the Medusa core. Its value can either be shared or isolated. Refer to the Modules documentation for more details.
    4. alias: a string indicating a unique alias to register the module under. Other modules can’t use the same alias.
    5. main: a boolean value indicating whether this module is the main registered module. This is useful when an alias is used.
Was this section helpful?