User Settings Management#

User settings updates in Zerobyte flow through Better Auth's updateUser endpoint, which is automatically generated for any fields declared under user.additionalFields in the server auth config. The Settings UI calls this endpoint directly — no custom API route is needed for profile field changes.

Server: Additional Fields via Better Auth#

In app/server/lib/auth.ts, four custom fields are registered on the user model:

Declaring a field here causes Better Auth to automatically expose it through the POST /api/auth/update-user endpoint — no additional server-side handler is required 1. The username and hasDownloadedResticPassword fields are marked returned: true, meaning they are included in session responses 2.

The user.modelName is set to "usersTable" 3, mapping to the schema definition which also stores dateFormat (default: "MM/DD/YYYY") and timeFormat (default: "12h") 4.

Client: authClient and inferAdditionalFields#

The client-side authClient is created with inferAdditionalFields<typeof auth>() 5, which pulls the additional field types from the server auth instance so that authClient.updateUser(...) is fully typed against those fields. Other plugins (usernameClient, adminClient, organizationClient, etc.) add their own methods to the same client object 6.

Settings UI: Auto-Save on Select Change#

Date/time format settings use an auto-save pattern — there is no explicit "Save" button. Instead, each <Select> fires onValueChange, which immediately calls authClient.updateUser(...).

These handlers are defined in the DateTimeFormatSection component:

• handleDateFormatChange — called on date format select change; skips the API call if the value is unchanged.
• handleTimeFormatChange — same pattern for time format.
• Both delegate to handleDateTimeFormatChange, which calls authClient.updateUser({ dateFormat, timeFormat, ... }) and triggers window.location.reload() on success to apply the new preferences.

The component also displays a live preview of the currently selected format before saving, using the formatDateTime utility from useTimeFormat.

Read-Only Fields#

username and email are rendered as disabled inputs in the Account Information section 9 — they cannot be changed from the Settings UI. Password changes go through authClient.changePassword(...) 10, which revokes other sessions on success and then automatically signs the user out.

Settings Page Structure#

The settings page at /(dashboard)/settings/ is rendered through settings-shell.tsx, which provides runtime-specific layouts:

• Desktop runtime — Renders a simplified settings view with only DateTimeFormatSection and (if permitted) RecoveryKeySection. Other settings sections (password, API keys, 2FA, organization tabs) are hidden in desktop mode.
• Web runtime — Renders the full SettingsPage component with two tabs:
  • Account — Account information, date/time format, password change, backup recovery key download, API keys, 2FA, passkeys.
  • Organization — Shown only to users with the organizationSettings.view permission; contains org details, member management, and SSO configuration.

Tab state (in web mode) is persisted in the URL via the ?tab= search param.

Key Files#