Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

1.7 KB
Raw Blame

Adding a Setting

To add a dashboard setting, define its default value, configure its form field and add translations. Settings are saved in the database.

Define the setting

Add a definition under the appropriate namespace:

{
  namespace: 'app',
  key: 'foo',
  type: 'string',
  defaultValue: 'bar',
  isPublic: true,
},

::: warning Keep credentials out of public settings Use isPublic only for values visitors may read. Use isSecret for credentials and isReadonly for values that normal setting updates must not change. An enum limits available string values. :::

Describe the form field

In server/services/settings/ui-config.ts, add the field to the namespace's UI configuration:

export const APP_SETTINGS_UI: Record<string, FieldUIConfig> = {
  foo: {
    type: 'input',
    help: 'settings.app.foo.help',
    required: true,
  },
}

Field types include input, password, URL, textarea, select, radio, tabs, toggle and number. Use visibleIf: { fieldKey: 'bar', value: 'baz' } when a field depends on another field's value.

Add translations and use the field

Add settings.app.foo.label, settings.app.foo.description and any help text to the locale files under i18n/locales/.

Existing forms use useSettingsForm('app') and render their descriptors through SettingField. For another namespace, use its corresponding UI configuration and form namespace. Server code reads and writes values through settingsManager.

::: tip Verify persistence and visibility Check that the field renders, saves and survives a restart. If it is private or secret, also check that it is absent from public settings responses. Database-backed settings do not normally require a new environment variable.

:::