import { CodeTabs, CodeTab } from "docs-ui"

export const metadata = { title: Settings Module, }

{metadata.title}

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.

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.

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:

export const highlights = [ ["12", "Modules.SETTINGS", "Resolve the module in a step."] ]

import { 
  createWorkflow, 
  WorkflowResponse,
  createStep,
  StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"

const setPreferenceStep = createStep(
  "set-preference",
  async ({}, { container }) => {
    const settingsModuleService = container.resolve(Modules.SETTINGS)

    const preference = await settingsModuleService
      .setUserPreference("user_123", "theme", {
        mode: "dark",
      })

    return new StepResponse({ preference })
  }
)

export const setPreferenceWorkflow = createWorkflow(
  "set-preference",
  () => {
    const { preference } = setPreferenceStep()

    return new WorkflowResponse({
      preference,
    })
  }
)

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

import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { setPreferenceWorkflow } from "../../workflows/set-preference"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await setPreferenceWorkflow(req.scope)
    .run()

  res.send(result)
}

import {
  type SubscriberConfig,
  type SubscriberArgs,
} from "@medusajs/framework"
import { setPreferenceWorkflow } from "../workflows/set-preference"

export default async function handleUserCreated({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  const { result } = await setPreferenceWorkflow(container)
    .run()

  console.log(result)
}

export const config: SubscriberConfig = {
  event: "user.created",
}

import { MedusaContainer } from "@medusajs/framework/types"
import { setPreferenceWorkflow } from "../workflows/set-preference"

export default async function myCustomJob(
  container: MedusaContainer
) {
  const { result } = await setPreferenceWorkflow(container)
    .run()

  console.log(result)
}

export const config = {
  name: "run-once-a-day",
  schedule: `0 0 * * *`,
}

Refer to the Workflows documentation to learn more.