Setting

How plugins contribute UI to the global settings page with AppRegistry.setting.add, and read/update settings via base-frontend hooks.

Overview

The shell owns the Settings hub. Plugins inject panels during register() with AppRegistry.setting.add, and use @quan-erp/base-frontend hooks to load and persist key/value settings (platform keys or plugin-owned keys).

Register UI with AppRegistry.setting.add({ pluginName, element })
Load with useSettingQuery({ mode: 'private' | 'public' })
Persist with useUpdateSettingQuery()
Prefer existing SettingKeys before inventing new ones

1. Register setting UI

In frontend/src/index.tsx, call AppRegistry.setting.add inside PluginModule.register. Pass pluginName (metadata.name) and a React element for your panel.

SettingComponents shape: { pluginName: string, element: ReactElement }
pluginName must equal module.metadata.json name
Keep the panel self-contained — load/save inside the component, not in register()

TSXfrontend/src/index.tsx

import type { AppRegistryState, PluginModule } from "@quan-erp/shared-types";
import metadata from "../module.metadata.json" with { type: "json" };
import { MyPluginSettings } from "./page/setting/my-plugin-settings";

const Plugin: PluginModule = {
  register(AppRegistry: AppRegistryState) {
    AppRegistry.setting.add({
      pluginName: metadata.name,
      element: <MyPluginSettings />,
    });
  },
};

export default Plugin;

2. Build the settings panel

Put panel UI under frontend/src/page/setting/ (or similar). Use base-frontend setting hooks and shared-ui form controls. Gate sensitive controls with the same APIs you use elsewhere (Protected / requiredApis).

TSXfrontend/src/page/setting/my-plugin-settings.tsx

import { useSettingContext, useSettingQuery } from "@quan-erp/base-frontend";

export function MyPluginSettings() {
  const { data: settings, isLoading } = useSettingQuery({ mode: "private" });
  const { onUpdateSetting, editedSetting } = useSettingContext();

  if (isLoading) return null;

  return (
    <div className="flex flex-col gap-4 p-4">
      <h3>My plugin</h3>
      {/* Bind controls to settings / editedSetting;
          call onUpdateSetting(key, value, datatype) on change */}
    </div>
  );
}

3. Settings hooks

Import hooks from @quan-erp/base-frontend.

useSettingQuery({ mode: 'private' | 'public' }, option?) — load setting map
useUpdateSettingQuery() — persist settings (wrapper uses { many: true })
useSettingStore — client cache; note double-call pattern useSettingStore()()
useSettingContext — onUpdateSetting(key, value, datatype, userId?, isPublic?), editedSetting
useIsContainInBottomNavBar(route) — whether a route is in mobile bottom-nav config

TSXread + update

import {
  useSettingQuery,
  useUpdateSettingQuery,
} from "@quan-erp/base-frontend";

const { data = {} } = useSettingQuery({ mode: "private" });
const updateSetting = useUpdateSettingQuery();

// Prefer useSettingContext().onUpdateSetting inside the Settings hub.
// For standalone flows:
await updateSetting.mutateAsync({ /* SettingMapValue */ });

4. Setting keys

Platform SettingKeys include LOCALE, THEME, DATE_FORMAT, TIMEZONE, BUSINESS_NAME, PRIMARY_COLOR, and more. Reuse them when your plugin should follow shell preferences. For plugin-specific config, use a clear namespaced key and a matching SettingDataType.

Private vs public mode — pick the mode that matches who should read the value
Do not invent duplicates of LOCALE / THEME / TIMEZONE
Align datatype with what onUpdateSetting / backend SettingService expect

Critical rules

Register only in register() via AppRegistry.setting.add
pluginName must match metadata.name
element is a ReactElement (JSX), not a component type
Use base-frontend setting hooks — do not bypass with ad-hoc axios to settings unless following platform APIs
Protect privileged controls with the same requiredApis pattern as pages

Checklist

Create page/setting panel component
AppRegistry.setting.add({ pluginName, element }) in register()
Wire useSettingQuery / useSettingContext (or useUpdateSettingQuery)
Reuse platform keys when applicable
Verify panel appears on Settings after quan-erp watch and install

Common failures

Panel missing — not registered, wrong pluginName, or plugin not installed
element type error — passed a component function instead of <Component />
Settings not loading — wrong mode (private vs public) or hooks used outside settings providers
Values not saving — onUpdateSetting / mutate not called, or datatype mismatch
Duplicate platform keys — overwriting LOCALE/THEME unexpectedly from a plugin panel