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
generalgroup is system-protected. Deleting any other group reassigns its settings togeneraland 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
| Behavior | Outcome |
|---|---|
| First-time apply | New 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 module | Reconciliation 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:
| Key | Replaces |
|---|---|
settingLabels.<setting code>.name | the setting's name |
settingLabels.<setting code>.description | the setting's description |
settingGroups.<group code>.name | the 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'sidfor 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 anHttpError. -
settingNoticeRegistry(SettingNoticeRegistryPort): a provider says that the stored platform-wide value is not what is in force, by answering{ code, message }, ornullwhen there is nothing to say. Every admin settings response then carries it asnotice; the key is absent otherwise. The Settings screen shows it under the description, translated from your bundle atsettingLabels.<setting code>.notice.<code>, elsemessage. A provider that throws is logged and skipped: the setting is shown without its notice.mfauses it formfa.admin.totp_enforcedwhen no encryption key is configured.A provider may also implement
confirmation, which says what to ask before a write:{ whenValue, code, message, params? }, ornull. The response then carries it asconfirmation. When an operator saves exactlywhenValue, the Settings screen re-reads the setting just before saving and asks with that read'sconfirmation, so a count inparamsis 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 atsettingLabels.<setting code>.confirmation.<code>filled in fromparams, elsemessage; declining saves nothing. After an accepted save the screen showssettingLabels.<setting code>.confirmed.<code>from your bundle, when you ship it, in place of the saved-count line. A provider whoseconfirmationthrows is logged and skipped, and the write is saved without asking.mfauses it formfa.admin.totp_enforced. The sign-out itself is not tied to the question:mfaends the sessions of administrators without a second factor after any write that leavesmfa.admin.totp_enforcedon, throughsettings.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:
| Setting | Type | What it is |
|---|---|---|
shop.logo_asset_id | string | Shop logo — a public image from the Assets Library, chosen with the asset picker. Empty publishes no logo. |
shop.social_profiles | string_list | Social 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
| Thrown | When |
|---|---|
SettingNotRegistered | The code has no row in settings. The caller has a typo or the module that should declare it has not been installed. |
SettingOutOfScopeForChannel | The 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. |
SettingValueShapeMismatch | The 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:
- Per-process LRU (1024 entries, entries older than 30 s ignored).
- Redis (
settings:v1:<code>:<channelId>, TTL 1h). - 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(withis_system_protectedfor the built-ingeneral)settings(FK →setting_groups, value-type enum,jsonbdefault)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.