@mostajs/settings

Reusable key-value settings module with typed factory, React provider, and auto-generated form.

Part of the @mosta suite.

Installation

npm install @mostajs/settings @mostajs/orm

Quick Start

1. Register schema and create settings module

import { registerSchema } from '@mostajs/orm'
import { SettingSchema, createSettingsModule } from '@mostajs/settings'

registerSchema(SettingSchema)

const DEFAULTS = {
  siteName: 'MyApp',
  maintenanceMode: false,
  theme: 'system' as 'light' | 'dark' | 'system',
}

export const { getSettings, updateSettings } = createSettingsModule({ defaults: DEFAULTS })

2. Use in API routes

const settings = await getSettings()
console.log(settings.siteName) // fully typed

await updateSettings({ maintenanceMode: true })

3. React provider & hook

import { SettingsProvider } from '@mostajs/settings/components/SettingsProvider'
import { useSettings } from '@mostajs/settings/hooks/useSettings'

// In layout:
<SettingsProvider defaults={DEFAULTS}>
  {children}
</SettingsProvider>

// In component:
const { settings, update } = useSettings()

4. Auto-generated admin form

import { SettingsForm } from '@mostajs/settings/components/SettingsForm'

<SettingsForm
  settings={settings}
  definitions={[
    { key: 'siteName', type: 'string', label: 'Site Name' },
    { key: 'maintenanceMode', type: 'boolean', label: 'Maintenance Mode' },
    { key: 'theme', type: 'select', label: 'Theme', options: ['light', 'dark', 'system'] },
  ]}
  onSave={handleSave}
/>

API Reference

| Export | Description | |--------|-------------| | createSettingsModule(config) | Factory returning typed getSettings() / updateSettings() | | SettingRepository | Repository with findByKey(), upsertByKey(), upsertMany() | | SettingSchema | Entity schema for registration | | createSettingsHandlers() | API route factory (GET/PUT) | | SettingsProvider | React context provider | | SettingsForm | Auto-generated settings form component | | useSettings() | React hook for settings context |

Related Packages

• @mostajs/orm — Multi-dialect ORM (required)

License

MIT — © 2025 Dr Hamid MADANI [email protected]