Skip to main content

Settings

The Settings module owns platform-wide configuration. Other modules contribute their own setting groups and individual settings through a typed manifest; platform administrators tune values per sales channel from the Admin UI; any backend module reads values through one well-known service.

Concepts​

  • Setting — a single tunable knob. Carries a name, a globally-unique machine code, a value type (string / number / boolean / json / string_list / secret / credential_ref), a manifest-supplied default value, and a sales-channel scope (empty scope means "applies to every channel").
  • Setting Value — an admin-chosen value for a (setting, sales_channel) pair. Replaces the manifest default for that channel. Resolution order is always: per-channel value → manifest default.
  • Setting Group — a logical section under which related settings appear in the Admin UI. The built-in general group is system-protected. Deleting any other group reassigns its settings to general and preserves their values.

For module authors — declaring your settings​

Each module that wants to register settings or groups builds a settings manifest with the helper from @endora-commerce/contracts and passes it as the settings field of its module manifest:

// packages/modules/<your_module>/src/manifest.ts
import {
defineModuleManifest,
defineModuleSettingsManifest,
} from '@endora-commerce/contracts';

const settings = defineModuleSettingsManifest({
moduleCode: 'your_module',
groups: [{ code: 'your_section', name: 'Your section' }],
settings: [
{
code: 'your_module.base_url',
name: 'Base URL',
groupCode: 'your_section', // optional — defaults to 'general'
valueType: 'string',
defaultValue: 'https://default.example',
// salesChannelCodes: ['main', 'wholesale'] // optional — empty = all
},
],
});

export const manifest = defineModuleManifest({
id: 'your_module',
// ...name, version, dependencies (include 'settings')...
settings,
});

There is no list to append to: the settings manifests are collected from the module registry (src/backend/services/registered-settings-manifests.ts in this module), so declaring settings on the manifest is the whole registration. The rows are written by the manifest reconciler, which inserts any missing groups and settings idempotently — at every boot for core and deployment overlay modules, and by module:install for a module installed as a package. Re-running is always safe; admin-chosen values are never overwritten.

Reconciler guarantees​

BehaviorOutcome
First-time applyNew groups + settings inserted; owner_module set to your module code.
Re-apply (no changes)No-op.
Re-apply (added entry)Only new entries are inserted.
Re-apply (renamed name/description)Updated in place.
Re-apply (added or removed multiline)Updated in place; stored values are not touched.
Re-apply (changed valueType or defaultValue)Rejected (BreakingChangeRejected) to keep existing per-channel values valid. No CLI flag overrides it. Two changes are accepted: string → secret, and a new defaultValue when the entry lists the stored one in previousDefaultValues.
Re-apply (entry removed from manifest)Boot sync ignores the removal — orphan rows are logged but not deleted. Only module:uninstall removes a module's settings.
Setting code conflicts with another moduleReconciliation aborts with a clear error.

Translating names and descriptions​

name and description in the manifest are English, and they are what the Settings screen shows unless your module's own bundle says otherwise. To show a setting in the administrator's language, add these keys to the i18n/en.json and i18n/pl.json your module already ships — flat keys, like every other key in a bundle:

KeyReplaces
settingLabels.<setting code>.namethe setting's name
settingLabels.<setting code>.descriptionthe setting's description
settingGroups.<group code>.namethe group's name

The code is written whole, dots included. For the manifest above:

{
"settingGroups.your_section.name": "Twoja sekcja",
"settingLabels.your_module.base_url.name": "Bazowy adres URL",
"settingLabels.your_module.base_url.description": "Adres, pod którym usługa jest dostępna."
}

Resolution is per key: the administrator's language, then English, then the string the manifest declared. Every key is optional, so a module that ships none of them renders exactly as it did before, and you can translate one setting at a time. Three things follow from how the lookup works:

  • Only the owning module's bundle is read — the module whose settings manifest declared the row (moduleCode, which must equal the module's id for its bundle to be found). A key for another module's setting is ignored.
  • The manifest strings stay required and stay English. They are what the API returns, what an administrator sees while a bundle is unavailable, and what the filter on the Settings screen also matches, next to the translated text.
  • The text is shown as written. There is no parameter substitution, so braces in a label are literal.

The choices of a setting declared with enumOptions are stored values and are shown untranslated. A group an operator created under Setting groups has no owning module and keeps the name it was given.

Multi-line text​

A string setting is edited in a single-line field. Declare multiline: true when the value is text with line breaks that matter — a block of instructions, a snippet, a footer note:

{
code: 'your_module.footer_note',
name: 'Footer note',
groupCode: 'your_section',
valueType: 'string',
defaultValue: '',
multiline: true,
},

The Settings screen then edits the value in a multi-line field, and the text is stored exactly as typed: line breaks, blank lines, indentation and a trailing line break are all kept. Nothing else changes — the value is still a string, is read with settingsService.get(code, channelId, z.string()), and resolves per sales channel like any other setting.

multiline is accepted only on valueType: 'string', and not together with enumOptions; any other combination is refused when the manifest is parsed. It is presentation, kept in step with the manifest on every reconciliation, so adding or removing it later is not a breaking change and leaves stored values alone. The admin API reports it as multiline on each setting, for a module that renders its own editor.

Two limits. The editors the Settings screen picks by convention take precedence over multiline: a setting with enumOptions keeps its dropdown, and a string whose code ends in _asset_id, or names an image and ends in _url, keeps its asset or image editor. And removing the flag does not rewrite anything: a stored value keeps its line breaks until an operator next edits it in the single-line field, which cannot hold them.

Validating writes, and saying a value is not in force​

Two contribution registries let the module that declared a setting answer for it, from a boot hook, while settings keeps owning storage and resolution. A contributor whose module is off is skipped by both.

  • settingWriteValidatorRegistry (SettingWriteValidatorRegistryPort): a validator refuses a value before it is stored, by throwing an HttpError.

  • settingNoticeRegistry (SettingNoticeRegistryPort): a provider says that the stored platform-wide value is not what is in force, by answering { code, message }, or null when there is nothing to say. Every admin settings response then carries it as notice; the key is absent otherwise. The Settings screen shows it under the description, translated from your bundle at settingLabels.<setting code>.notice.<code>, else message. A provider that throws is logged and skipped: the setting is shown without its notice. mfa uses it for mfa.admin.totp_enforced when no encryption key is configured.

    A provider may also implement confirmation, which says what to ask before a write: { whenValue, code, message, params? }, or null. The response then carries it as confirmation. When an operator saves exactly whenValue, the Settings screen re-reads the setting just before saving and asks with that read's confirmation, so a count in params is the one in force at save time; if the re-read carries none, it saves without asking. The question is the text from your bundle at settingLabels.<setting code>.confirmation.<code> filled in from params, else message; declining saves nothing. After an accepted save the screen shows settingLabels.<setting code>.confirmed.<code> from your bundle, when you ship it, in place of the saved-count line. A provider whose confirmation throws is logged and skipped, and the write is saved without asking.

    mfa uses it for mfa.admin.totp_enforced. The sign-out itself is not tied to the question: mfa ends the sessions of administrators without a second factor after any write that leaves mfa.admin.totp_enforced on, through settings.value_changed. The question is asked only when a save turns it on, with how many administrators that is.

ctx.onBoot(() => {
lazyPort<SettingNoticeRegistryPort>(ctx, 'settingNoticeRegistry').register({
contributorModuleId: 'your_module',
codes: ['your_module.enabled'],
notice: async ({ value }) =>
value === true && !configured()
? { code: 'not_configured', message: 'Not in force: the connection is not configured.' }
: null,
});
});

For platform admins — editing values​

Open Admin → Operations → Settings. Settings are grouped by their owning section. Selecting one opens an editor on the right; you can:

  • Apply a value to every sales channel in scope in one click.
  • Apply a value to a chosen subset of channels (the editor enforces the "at least one channel" rule).
  • Reset the per-channel values back to the manifest default.

Concurrent edits are detected via an expectedVersion (ISO timestamp). If someone else has changed the setting since you opened it, the save returns 409 VERSION_CONFLICT and a banner asks you to refresh and retry — no silent overwrites.

Setting groups are managed under Admin → Operations → Setting groups. The general group is system-protected; the platform refuses to delete it. Deleting any other group reassigns its settings to general and preserves their per-channel values.

Every value change and group mutation lands an audit_log_entries row with the actor, action, target, and new value. A value write or reset also records the stored value it replaced or removed, so the audit log viewer shows before and after side by side. That is the value stored at the level being written — the all-channels value, or that channel's own — and not the value the channel resolved to: a first write records stored: false rather than the manifest default. A secret setting is recorded as [redacted] on both sides.

Shop information​

The Shop information group (shop) holds the facts about the shop that the storefront publishes: shop.name, shop.address, shop.contact_email, shop.support_email, shop.phone, shop.contact_form_recipient_emails, and two settings for search engines:

SettingTypeWhat it is
shop.logo_asset_idstringShop logo — a public image from the Assets Library, chosen with the asset picker. Empty publishes no logo.
shop.social_profilesstring_listSocial profiles — the full https:// addresses of the organisation's profiles on social networks and other sites, one per entry. A write holding any other value is refused with 422 VALIDATION_FAILED and nothing is stored.

The storefront reads them through GET /api/v1/storefront/shop-info, which returns logoUrl (the logo asset's public URL, or null when the setting is empty or the asset is gone or not public) and socialProfiles (only https: entries). It publishes both in its Organization structured data, as logo and sameAs, on the home page and on every CMS page. Resolving the logo is why this module depends on assets_library.

For module consumers — reading values​

Other modules inject SettingsService from the composition root and read through a single API. The result is always either the admin-chosen value for the requested channel or the manifest default.

import { z } from 'zod';

// In your module's plugin:
const baseUrl = await settingsService.get(
'your_module.base_url',
request.salesChannelId,
z.string().url(),
);

Errors​

ThrownWhen
SettingNotRegisteredThe code has no row in settings. The caller has a typo or the module that should declare it has not been installed.
SettingOutOfScopeForChannelThe setting was registered with an explicit channel scope and the requested channel is not in that scope. Indicates a programmer error: the consuming module should not be reading this setting in this context.
SettingValueShapeMismatchThe stored value passed Zod validation at write time but failed the caller's schema (e.g. an admin set the value via a manifest with a wider type). Surfaced as a fail-fast misconfiguration.

Performance​

The universal getter is cheap enough to call freely from request paths. Resolution order:

  1. Per-process LRU (1024 entries, entries older than 30 s ignored).
  2. Redis (settings:v1:<code>:<channelId>, TTL 1h).
  3. Postgres (one keyed lookup against (setting_id, sales_channel_id)).

Cache invalidation hangs off the EventBus events that the admin service emits on every value or group mutation. The EventBus is in-process, so the writing process picks the change up immediately, and every other process picks it up on its next read past the 30 s window — invalidation dropped the shared Redis entry, and the local window is measured from when the value was loaded rather than from the last read, so even a setting read on every request ages out.

That window is the bound on how long a missed invalidation can be visible. It is also why the operator-facing "clear cache" page is a diagnostic tool rather than a repair: it drops both layers in the process that serves it and the shared entries for everyone, and every other process converges within the same 30 s.

CLI​

Settings rows are installed and removed by the module lifecycle commands, not by commands of their own. Run them in the root of the instance:

# Install a module: runs its migrations and reconciles its settings manifest.
pnpm run module:install <module-id> [--dry-run] [--json]

# Soft uninstall (default): unregisters the module's settings and marks the
# module uninstalled; its tables and data stay. --hard also reverts the
# module's migrations and must be combined with --force.
pnpm run module:uninstall <module-id> [--hard --force] [--json]

In a checkout of the Endora Commerce repository the same two commands are pnpm --filter backend run module:install and pnpm --filter backend run module:uninstall, with the same arguments.

--remove-settings and --preserve-settings are still accepted by module:uninstall for backward compatibility: the first means --hard --force, the second does nothing. The argument grammar and exit codes belong to @endora-commerce/platform's lifecycle commands; the Module lifecycle page lists the exit codes. Both commands write audit_log_entries rows.

Database​

Five tables introduced by the platform migration packages/platform/src/migrations/20260430T101450_core_settings_init.ts:

  • setting_groups (with is_system_protected for the built-in general)
  • settings (FK → setting_groups, value-type enum, jsonb default)
  • setting_values (per-(setting, sales_channel) admin override; UNIQUE)
  • setting_group_sales_channels (M:N scope)
  • setting_sales_channels (M:N scope; empty = all channels)

setting_values.sales_channel_id cascade-deletes when the channel is removed; remaining bindings on the same setting are preserved.