Help

Settings Module

In this section of the documentation, you will find resources to learn more about the Settings Module and how to use it in your application.

Looking for no-code docs? Refer to the Medusa Admin User Guide to learn how to customize data tables and manage views in the dashboard.

Medusa has admin personalization and configuration features available out-of-the-box through the Settings Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features is provided in Commerce Modules, such as the Settings Module.

The Settings Module powers dashboard personalization features, such as configuring data tables, customizing page layouts, and storing user preferences.

Note: Refer to the Module Isolation guide to learn more about why modules are isolated.

Settings Features#

View Configurations: Store data-table views for an entity, including visible columns, column order and widths, filters, sorting, and search. Views can be personal to a user or a shared system default.
Layout Configurations: Store per-zone layout preferences, such as the order and visibility of sections on a page, for a user or as a shared system default.
Property Labels: Set custom, translatable labels and descriptions for an entity's properties.
User Preferences: Store arbitrary preferences for a user as key-value pairs.

How to Use the Settings Module#

In your Medusa application, you build flows around Commerce Modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and a reliable rollback mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

src/workflows/set-preference.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7import { Modules } from "@medusajs/framework/utils"8
9const setPreferenceStep = createStep(10  "set-preference",11  async ({}, { container }) => {12    const settingsModuleService = container.resolve(Modules.SETTINGS)13
14    const preference = await settingsModuleService15      .setUserPreference("user_123", "theme", {16        mode: "dark",17      })18
19    return new StepResponse({ preference })20  }21)22
23export const setPreferenceWorkflow = createWorkflow(24  "set-preference",25  () => {26    const { preference } = setPreferenceStep()27
28    return new WorkflowResponse({29      preference,30    })31  }32)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

Refer to the Workflows documentation to learn more.

Was this page helpful?