@medusajs/settings 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +86 -0
  2. package/README.md +90 -11
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,86 @@
1
+ # @medusajs/settings
2
+
3
+ Commerce module that stores admin UI settings: data table view configurations, admin layout configurations, per-user preferences, and custom property labels. It also discovers entities from module joiner configs to generate admin table columns. Registered as `Modules.SETTINGS` (`"settings"`).
4
+
5
+ ## Using this package
6
+
7
+ - Loaded by default through `defineConfig` (`@medusajs/medusa/settings`). No providers.
8
+ - The `/admin/views/[entity]/...` routes are gated by the `view_configurations` feature flag (`MEDUSA_FF_VIEW_CONFIGURATIONS`, default `false`); `/admin/layouts/configurations` is not. The module itself always loads.
9
+ - Only option: `entityOverrides` (`SettingsModuleOptions` in `src/types/index.ts`), merged into the built-in override registry at construction:
10
+
11
+ ```ts
12
+ module.exports = defineConfig({
13
+ modules: [
14
+ {
15
+ resolve: "@medusajs/medusa/settings",
16
+ options: {
17
+ entityOverrides: {
18
+ Brand: {
19
+ defaultVisibleFields: ["name", "products_count"],
20
+ defaultFieldOrdering: { name: 100 },
21
+ computedColumns: [
22
+ {
23
+ id: "products_count",
24
+ name: "Product Count",
25
+ renderMode: "count",
26
+ requiredFields: ["products"],
27
+ },
28
+ ],
29
+ },
30
+ },
31
+ },
32
+ },
33
+ ],
34
+ })
35
+ ```
36
+
37
+ - Resolve with `container.resolve(Modules.SETTINGS)`, typed `SettingsTypes.ISettingsModuleService` from `@medusajs/framework/types`.
38
+ - The package also exports its column utilities (`src/utils`: entity discovery, overrides, computed columns, render modes, filter rules).
39
+
40
+ ### Data models (`src/models`)
41
+
42
+ - `ViewConfiguration` (`vconf_`): `entity`, `name`, `user_id` (null for system defaults), `is_system_default`, `configuration` JSON (`visible_columns`, `column_order`, `column_widths`, `filters`, `sorting`, `search`).
43
+ - `LayoutConfiguration` (`lyconf_`): `zone`, `user_id`, `is_system_default`, `configuration`. Unique `(zone, user_id)` plus at most one system default per zone (partial unique index).
44
+ - `UserPreference` (`usrpref_`): `user_id`, `key`, `value` JSON, unique `(user_id, key)`.
45
+ - `PropertyLabel` (`plbl_`): `entity`, `property`, `label` and `description` (translatable), unique `(entity, property)`.
46
+
47
+ ### Service methods (`src/services/settings-module-service.ts`)
48
+
49
+ Generated CRUD for all four models, plus:
50
+
51
+ - Views: overridden `createViewConfigurations` / `updateViewConfigurations`, `getActiveViewConfiguration(entity, userId)`, `setActiveViewConfiguration(entity, userId, id)`, `clearActiveViewConfiguration`, `getSystemDefaultViewConfiguration(entity)`.
52
+ - Layouts: `setLayoutConfiguration(zone, userId, ...)`, `setSystemDefaultLayoutConfiguration(zone, ...)`, `getSystemDefaultLayoutConfiguration(zone)`, `clearLayoutConfiguration`, `getActiveLayoutScope` / `setActiveLayoutScope` (`"personal" | "default" | null`).
53
+ - Preferences: `getUserPreference(userId, key)`, `setUserPreference(userId, key, value)`.
54
+ - Columns: `upsertPropertyLabels`, `listDiscoverableEntities`, `generateEntityColumns(entityKey)`, `hasEntity`, `isEntityDiscoveryInitialized`.
55
+
56
+ ### Events and links
57
+
58
+ - Emits internal CRUD events (`settings.<model>.created|updated|deleted|restored`) through `MedusaService`.
59
+ - No module links; `user_id` is a plain text column, not a link to the User Module.
60
+
61
+ Docs: https://docs.medusajs.com/resources/commerce-modules/settings.md, https://docs.medusajs.com/resources/commerce-modules/settings/view-configurations.md, https://docs.medusajs.com/resources/commerce-modules/settings/configure-view-configurations.md, https://docs.medusajs.com/resources/commerce-modules/settings/layout-configurations.md
62
+
63
+ ## Architecture
64
+
65
+ - Entity discovery is initialized in `__hooks.onApplicationStart` from `MedusaModule.getAllJoinerConfigs()`. Before that, `listDiscoverableEntities` returns `[]` and `generateEntityColumns` returns `null`.
66
+ - Active view and layout scope are stored as user preferences under keys `active_view.<entity>` and `active_layout.<zone>`.
67
+ - Source imports use the `@/models`, `@/services` tsconfig aliases, unlike the `@models` form other modules use.
68
+
69
+ ## Development
70
+
71
+ ```bash
72
+ cd packages/modules/settings
73
+ yarn build
74
+ yarn test
75
+ yarn test:integration # integration-tests/__tests__ (needs Postgres, DB_* env vars)
76
+ yarn migration:create # after any change in src/models
77
+ ```
78
+
79
+ - Integration tests: `settings-module.spec.ts`, `entity-discovery.spec.ts`, `property-labels.spec.ts`; joiner-config fixtures in `integration-tests/__fixtures__/`.
80
+
81
+ ## Gotchas
82
+
83
+ - Updating a view's `configuration` replaces the whole JSON (via `upsertWithReplace`); missing keys reset to defaults (`[]`, `{}`, `null`, `""`). Send the full configuration.
84
+ - A system default view cannot have a `user_id` (`INVALID_DATA`), and only one system default per entity is allowed (`DUPLICATE_ERROR`).
85
+ - `setActiveViewConfiguration` throws if the view belongs to another entity or to another user.
86
+ - `getActiveViewConfiguration` falls back from the stored preference, to the user's oldest personal view, to the system default. A stored `viewConfigurationId: null` skips the personal-view fallback.
package/README.md CHANGED
@@ -1,17 +1,96 @@
1
- # Settings Module
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/settings
12
+ </h1>
2
13
 
3
- The settings module provides functionality for managing user preferences and configurations in Medusa.
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ Settings Module for Medusa: manages view configurations, layout configurations, property labels, and user preferences. Use it to store admin dashboard personalization, such as data-table views, page layouts, and per-user preferences. It ships with `@medusajs/medusa` and is registered by default, so Medusa applications don't install it directly.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/settings` |
44
+ | Type | Commerce Module |
45
+ | Module key | `Modules.SETTINGS` (`"settings"`) |
46
+ | Registered by default | Yes |
47
+ | Import from | `@medusajs/medusa/settings` |
4
48
 
5
49
  ## Features
6
50
 
7
- - **View Configurations**: Save and manage table view configurations (column visibility, order, widths)
8
- - **User Preferences**: Store arbitrary user preferences in a key-value format
9
- - **System Defaults**: Admin users can set default configurations for all users
51
+ - Store data-table view configurations per entity, personal to a user or as a shared system default.
52
+ - Store per-zone layout configurations for a user or as a system default.
53
+ - Set custom labels and descriptions for an entity's properties.
54
+ - Store arbitrary user preferences as key-value pairs.
55
+
56
+ The Admin API routes for view configurations require the `view_configurations` feature flag (`MEDUSA_FF_VIEW_CONFIGURATIONS`), which is disabled by default.
57
+
58
+ ## Installation
59
+
60
+ No installation needed. The module is included in `@medusajs/medusa` and registered by default.
61
+
62
+ ## Usage
63
+
64
+ Resolve the module's service from the container, for example in a workflow step:
65
+
66
+ ```ts
67
+ import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
68
+ import { Modules } from "@medusajs/framework/utils"
69
+
70
+ const setPreferenceStep = createStep(
71
+ "set-preference",
72
+ async ({}, { container }) => {
73
+ const settingsModuleService = container.resolve(Modules.SETTINGS)
74
+
75
+ const preference = await settingsModuleService
76
+ .setUserPreference("user_123", "theme", {
77
+ mode: "dark",
78
+ })
79
+
80
+ return new StepResponse({ preference })
81
+ }
82
+ )
83
+ ```
84
+
85
+ ## Configuration
86
+
87
+ | Option | Type | Description | Default |
88
+ | --- | --- | --- | --- |
89
+ | `entityOverrides` | `Record<string, EntityOverride>` | Overrides for how an entity's columns appear in data tables, such as default visible fields, field ordering, and computed columns, keyed by entity name. Merged with the built-in overrides, and your values take precedence. | `{}` |
10
90
 
11
- ## Module Options
91
+ ## Resources
12
92
 
13
- ```js
14
- const settingsModuleOptions = {
15
- // Module options can be added here if needed
16
- }
17
- ```
93
+ - [Settings Module](https://docs.medusajs.com/resources/commerce-modules/settings)
94
+ - [Configure view configurations](https://docs.medusajs.com/resources/commerce-modules/settings/configure-view-configurations)
95
+ - [View configurations](https://docs.medusajs.com/resources/commerce-modules/settings/view-configurations)
96
+ - [User preferences](https://docs.medusajs.com/resources/commerce-modules/settings/user-preferences)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/settings",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa Settings module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -39,10 +43,10 @@
39
43
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
40
44
  },
41
45
  "devDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
43
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
46
+ "@medusajs/framework": "2.22.0",
47
+ "@medusajs/test-utils": "2.22.0"
44
48
  },
45
49
  "peerDependencies": {
46
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
50
+ "@medusajs/framework": "2.22.0"
47
51
  }
48
52
  }