settings-and-preferences
Builds app settings - saved fields, defaults, rows, each setting's effect, resets that keep them. Use when adding a setting or toggle, or a setting is ignored or lost on restart. Not for theme tokens (design-system-structure).
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 13
- Forks
- 2
01 前言 Front Matter
- name
- settings-and-preferences
- description
- Builds app settings - saved fields, defaults, rows, each setting's effect, resets that keep them. Use when adding a setting or toggle, or a setting is ignored or lost on restart. Not for theme tokens (design-system-structure).
02 资源文件 92
- 资产文件assets/shared.json747 B
- 资产文件assets/template-placeholders.json68 B
- 其他examples/app-providers.tsx1.3 KB
- 其他examples/app-root.tsx4.2 KB
- 其他examples/root-layout.tsx3.8 KB
- 参考文档examples/settings-contract-document-mode.json2.6 KB
- 其他examples/settings-route.tsx2.7 KB
- 其他examples/settings-screen.tsx6.2 KB
- 脚本examples/use-settings-input.ts3.1 KB
- 参考文档references/rows-and-controls.md16.2 KB
- 参考文档references/settings-model.md26.3 KB
- 脚本scripts/check-lib.mjs117.1 KB
- 脚本scripts/check-settings.mjs32.0 KB
- 脚本scripts/lib/object-literal.mjs3.5 KB
- 脚本scripts/selftest.mjs579 B
- 参考文档templates/contracts/settings.json3.0 KB
- 参考文档templates/contracts/settings.schema.json7.6 KB
- 脚本templates/src/config/external-links.test.ts2.0 KB
- 脚本templates/src/config/external-links.ts2.2 KB
- 脚本templates/src/data/open-device-settings.ts877 B
- 脚本templates/src/features/settings-effects/connect-sound-settings.test.ts1.9 KB
- 脚本templates/src/features/settings-effects/connect-sound-settings.ts1.5 KB
- 脚本templates/src/features/settings-effects/haptics-gate.test.ts1.4 KB
- 脚本templates/src/features/settings-effects/haptics-gate.ts1.3 KB
- 其他templates/src/features/settings-effects/preferences-root.test.tsx3.8 KB
- 其他templates/src/features/settings-effects/preferences-root.tsx2.6 KB
- 脚本templates/src/features/settings-effects/read-saved-language.test.ts1.5 KB
- 脚本templates/src/features/settings-effects/read-saved-language.ts942 B
- 脚本templates/src/features/settings/data-resets.test.ts3.7 KB
- 脚本templates/src/features/settings/data-resets.ts2.0 KB
- 脚本templates/src/features/settings/language-change.test.ts1.6 KB
- 脚本templates/src/features/settings/language-change.ts1.7 KB
- 脚本templates/src/features/settings/settings-preference-actions.test.ts2.7 KB
- 脚本templates/src/features/settings/settings-preference-actions.ts2.7 KB
- 脚本templates/src/features/settings/settings-rows.test.ts2.7 KB
- 脚本templates/src/features/settings/settings-rows.ts5.1 KB
- 其他templates/src/features/settings/use-settings-model.test.tsx7.3 KB
- 脚本templates/src/features/settings/use-settings-model.ts6.1 KB
- 参考文档templates/src/i18n/catalogs/ar.json3.1 KB
- 参考文档templates/src/i18n/catalogs/en.json2.5 KB
- 脚本templates/src/services/settings-storage/fake-settings-storage.test.ts1.3 KB
- 脚本templates/src/services/settings-storage/fake-settings-storage.ts1.2 KB
- 脚本templates/src/services/settings-storage/kv-settings-storage-adapter.ts1.5 KB
- 脚本templates/src/services/settings-storage/settings-storage-port.ts1.1 KB
- 脚本templates/src/stores/settings/settings-codec.test.ts2.8 KB
- 脚本templates/src/stores/settings/settings-codec.ts3.1 KB
- 脚本templates/src/stores/settings/settings-reducer-cases.ts3.5 KB
- 脚本templates/src/stores/settings/settings-reducer.test.ts2.5 KB
- 脚本templates/src/stores/settings/settings-reducer.ts2.4 KB
- 脚本templates/src/stores/settings/settings-schema.test.ts1.0 KB
- 脚本templates/src/stores/settings/settings-schema.ts1.5 KB
- 脚本templates/src/stores/settings/settings-selectors.test.ts1.7 KB
- 脚本templates/src/stores/settings/settings-selectors.ts1.5 KB
- 其他templates/src/stores/settings/settings-store-context.test.tsx2.2 KB
- 其他templates/src/stores/settings/settings-store-context.tsx779 B
- 脚本templates/src/stores/settings/settings-store.test.ts3.1 KB
- 脚本templates/src/stores/settings/settings-store.ts3.9 KB
- 参考文档tests/bases/app/package.json212 B
- 脚本tests/bases/app/src/data/reset-data.ts483 B
- 脚本tests/bases/app/src/features/settings/use-settings-input.ts449 B
- 参考文档tests/bases/app/tsconfig.json137 B
- 参考文档tests/fixtures/bad-async-hydrate/EXPECT.txt103 B
- 参考文档tests/fixtures/bad-clear-in-handler/EXPECT.txt334 B
- 参考文档tests/fixtures/bad-default-mismatch/EXPECT.txt122 B
- 参考文档tests/fixtures/bad-loose-schema/EXPECT.txt46 B
- 参考文档tests/fixtures/bad-missing-case/EXPECT.txt39 B
- 参考文档tests/fixtures/bad-no-clamp/EXPECT.txt62 B
- 参考文档tests/fixtures/bad-no-contract/EXPECT.txt46 B
- 参考文档tests/fixtures/bad-no-effect/EXPECT.txt97 B
- 参考文档tests/fixtures/bad-no-row/EXPECT.txt56 B
- 参考文档tests/fixtures/bad-no-toggle-feedback/EXPECT.txt57 B
- 参考文档tests/fixtures/bad-publish-first/EXPECT.txt91 B
- 参考文档tests/fixtures/bad-reset-bare-update/EXPECT.txt181 B
- 参考文档tests/fixtures/bad-reset-clears-store/EXPECT.txt79 B
- 参考文档tests/fixtures/bad-reset-replaces-settings/EXPECT.txt95 B
- 参考文档tests/fixtures/bad-restart-always/EXPECT.txt113 B
- 参考文档tests/fixtures/bad-side-copy/EXPECT.txt145 B
- 参考文档tests/fixtures/bad-unit-scale/EXPECT.txt130 B
- 参考文档tests/fixtures/bad-unknown-setting/EXPECT.txt44 B
- 参考文档tests/fixtures/bad-validator-changed/EXPECT.txt135 B
- 参考文档tests/fixtures/bad-zustand-persist/EXPECT.txt74 B
- 参考文档tests/fixtures/CASES.json20.1 KB
- 参考文档tests/fixtures/error-bad-contract/EXPECT.txt60 B
- 参考文档tests/fixtures/error-no-package/EXPECT.txt52 B
- 参考文档tests/fixtures/error-unknown-action/EXPECT.txt78 B
- 参考文档tests/fixtures/good/EXPECT.txt29 B
- 参考文档tests/fixtures/pass-document-mode/EXPECT.txt29 B
- 参考文档tests/fixtures/pass-no-settings/EXPECT.txt130 B
- 参考文档tests/fixtures/pass-own-clear-methods/EXPECT.txt13 B
- 参考文档tests/fixtures/pass-reset-block-body/EXPECT.txt13 B
- 参考文档tests/fixtures/pass-reset-not-yet-created/EXPECT.txt120 B
- 参考文档tests/fixtures/SUITE.json1.5 KB
03 SKILL.md 正文
Settings and preferences
Every setting is saved in one place, changed by one action, shown by one row, and applied by code outside the settings screen, at once and without a Save button; data resets never touch it, and a checker proves the whole chain against the app's own settings contract on iOS and Android alike.
Rules that must hold
- One settings model, one owner. Every saved preference is a field of one strict valibot object
(
SETTINGS_SCHEMAinsrc/stores/settings/) and is listed incontracts/settings.jsonwith its validator, first-launch value, action and effect; nothing else keeps a copy (nouseStatemirror, no side cache, no zustandpersist, no second key-value write). Why: one place to read, change and decode, so a restart can never show an older value. (settings-schema,single-writer) - Saved through one synchronous adapter, read before the first paint. Default:
expo-sqlite/kv-storebehindSettingsStoragePort, one JSON value under one key, read in the root layout's first-render initializer. Why: the first frame already has the saved theme and language, and one key is one atomic write. (hydrate-sync) - Reduce, persist, then publish; a failed write publishes nothing. The screen never shows a value
that is not saved, the failure is shown (
settings.save-failed), and storage that cannot be read runs the session in memory without overwriting it. No Save button, no delayed write. (persist-then-publish) - One pure reducer action per change; ranges clamped in the reducer. Imperative kebab-case
(
set-theme), a no-op returns the same object (nothing written), integer percent rounded and clamped with a property test. Why: every change is testable without React and replays the same. (reducer-action) - Decode field by field; a stored field never changes shape in place. A missing field takes its default quietly, an unreadable one falls back alone and is recorded, a new meaning gets a new field name, and a frozen sample of every shipped shape keeps decoding. Why: the key-value store has no migrations, and one bad value must never reset every setting.
- First-launch values follow the phone; noise is opt-in. Settings that mirror a phone setting
(language, theme, reduce motion, digits) start at
'system'/null; sound and anything that interrupts start off; every other value is a product decision written in the contract. (settings-default) - Every setting has an effect outside the settings code, applied at once, through one of four
mechanisms: a provider re-render (
PreferencesRootfeedsI18nProvider,AppThemeProvider preference, the reduce-motion preference context the root stack'sRootMotionhands toMotionConfig), a store subscription started at startup that returns its unsubscribe (sound), an adapter that reads the store at call time (the haptics gate: created before the services, connected once the store opens, silent until then), or a feature hook reading a selector. Why: a setting nothing reads is a bug people see. (setting-effect) - Store canonical units; convert at the edge. The volume is integer percent;
toSoundOutputdivides by 100 for the 0..1 an audio API takes; a 0..1 slider dispatches only when the whole percent changes. (unit-scale) - Every row dispatches its action; rows that do not apply are hidden, never greyed. Visibility
is the pure
settingsGroupsFor(context)over facts (haptics supported, Premium owned, a consent entry point needed), each rule unit-tested; testIDs and label keys come from one typed table. Why: a disabled control nobody can enable is noise for VoiceOver and TalkBack. (row-dispatch) - A language change switches the text at once; only a layout-direction flip restarts, after
the person confirms.
planLanguageChangecompares the new language's direction with the layout's and the choice is saved either way. Why: React Native applies a direction at the next start, and a needless restart throws away state. (restart-on-direction-only) - Resets never touch the settings. "Delete all data" (
createDataResets) deletes data through the data layer (persistence-and-migrations owns the SQL) and keeps settings and purchases (and first-run flags, unless the product decides otherwise); no code outside the storage adapter clears a whole key-value store (Storage.clearSync(),AsyncStorage.clear()); a failed delete is shown, never silent; "Reset settings" is its own action and confirmation; a save-document reset is one write insideupdateAndPublish's callback. (reset-keeps-settings,reset-publish) - A switch plays its feedback once, after the dispatch (the model input
onToggled, which callsplayUiFeedback(services, 'toggle'); never the press feedback); sliders and segments play none. Why: the feedback reads the settings at call time, so "sound off" is already silent. (toggle-feedback, when the contract sets it) - Reduce motion is tri-state. The switch shows the resolved value (
useReduceMotion()) and writes the opposite explicitly ('on'/'off'); accessibility-as-code owns the resolution and the ban on Reanimated'suseReducedMotion, and design-system-structure owns the theme provider.
Workflow
-
Read references/settings-model.md: where each piece lives, the fields and first-launch values, persistence, decoding, the effects table, iOS and Android, resets, the contract keys and every checker rule.
-
New settings model.
npx expo install expo-sqlite expo-localization, thennpm install -E zustand@5.0.15 valibot@1.5.0(stack table, verified 2026-10-03; re-verify withnpm view zustand@5 version). Copytemplates/src/stores/settings/(schema, codec, reducer and itssettings-reducer-cases.tstable, selectors, store),templates/src/services/settings-storage/,templates/src/data/open-device-settings.tsandtemplates/contracts/tocontracts/. Replace the Tasks fields with the app's own, in the contract first, then the schema, defaults, codecv.fallbacklines, actions, reducer cases and selectors. -
Wire the startup (copy
templates/src/features/settings-effects/): in the root layout'sdecideStartupcreate the gate (createHapticsGate()) beforecreateDeviceServices, whose haptics adapter takesgate.isEnabled, and resolve the language fromreadSavedLanguage(...)(examples/root-layout.tsx); in AppRoot'sstartApp, after the data layer and the error sink, open the store (openDeviceSettings(errorLog)), thengate.connect(settings)andconnectSoundSettings(audio-and-haptics-feedback owns both ports); renderSettingsStoreProviderandPreferencesRootin place of fixed provider values; the canonicalroot-stack.tsxstays as it is (itsRootMotionreads the preferencePreferencesRootprovides) (examples/app-root.tsx, examples/app-providers.tsx). -
The screen. Read references/rows-and-controls.md. Copy
templates/src/features/settings/andtemplates/src/config/external-links.ts, mergetemplates/src/i18n/catalogs/*.jsoninto the app's catalogs (translate for every app language), add the route as examples/settings-route.tsx and the view as examples/settings-screen.tsx with the ui-component-library rows and the three confirm dialogs; gather the row facts (signed in, haptics, Premium, consent) and thedataResetswiring (updateAndPublisharound the data layer's reset) as examples/use-settings-input.ts. FillPRIVACY_POLICY_PAGE: its test fails while the placeholder is left in. The account rows hand off to auth-and-secure-storage. -
Adding or changing a setting: follow "Adding or changing a setting" in the model reference: contract, schema and defaults, codec line and a frozen sample, action (test first), selector, row, effect. A new setting is a product decision: ask the developer first.
-
Save document instead of the key-value store (persistence-and-migrations' document mode): use examples/settings-contract-document-mode.json as the contract and read the model reference's appendix.
-
Test, then
npm run typecheck:npx jest src/stores/settings src/services/settings-storage src/features/settings \ src/features/settings-effects src/config --ci --maxWorkers=2 -
On devices, after a change to the storage or the startup: change the theme, kill and relaunch on a named iOS simulator and a named Android emulator (commands in the rows reference); the first frame must show the saved theme. Without devices, say in the report that this check is owed.
-
Run the checker from the repo root:
node ${CLAUDE_SKILL_DIR}/scripts/check-settings.mjs .; fix everyFAILline (file, rule and fix are printed) and rerun until it printsRESULT: PASS.
Definition of done
- [ ]
contracts/settings.jsonlists every field (validator, first-launch value, action, effect) and every action; schema and defaults match it, and the codec has av.fallbackline per field. - [ ] The store hydrates synchronously, persists before it publishes, publishes nothing on a failed write, and never writes when the saved settings could not be read; its tests pass.
- [ ] Every action has a reducer case and a test; every range is clamped with a property test; the codec test holds a frozen sample of every shipped shape.
- [ ] Every row dispatches its action; hidden rows follow
settingsGroupsForand its tests; row testIDs and labels come from the typed tables and every app catalog has the keys. - [ ] Every field's effect is wired and tested outside the settings code; percent values are converted at the edge.
- [ ] A language of the other direction opens "Restart to apply"; the same direction switches at once.
- [ ] Data resets keep the settings and purchases (first-run flags as the product decided), and a
failed delete shows
settings.delete-all-data.failed; "Reset settings" is its own confirmed action. - [ ] The Privacy policy row opens the app's real https page (
PRIVACY_POLICY_PAGEfilled in). - [ ] The restart check passed on a named iOS simulator and a named Android emulator, or the report says it is owed.
- [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-settings.mjs .printsRESULT: PASS(expected only before the data layer exists:SKIP src/data/reset-data.ts [reset-keeps-settings] not yet created (persistence-and-migrations creates it); an app with no settings printsNOT APPLICABLE).
Anti-patterns
- A local
useStatecopy of a setting in the screen. It drifts from the store and skips the save; read the store and dispatch. - A Save button or a debounced write. Every change is saved at once; the store already persists before it publishes.
- Loading settings with an async API after the first render. The app flashes the default theme and language; read synchronously in the first-render initializer.
- zustand's
persistmiddleware or AsyncStorage for settings. A second, unversioned copy that publishes before it saves; use the storage port. - One storage key per field. A two-field change becomes two writes and can be half saved; one JSON value under one key.
- Resetting every setting because one saved value is unreadable. Decode field by field.
- Reading
settings.reduceMotionorsettings.themedirectly in a component.'system'must resolve against the phone; the providers anduseReduceMotion()do that. - Passing the stored percent to a 0..1 API or a 0..1 slider value straight into the store. Convert at the edge; dispatch only whole-percent changes.
- Greying out rows that do not apply. Hide them, from the pure visibility function.
- Restarting for every language change, or opening the restart dialog after a failed save (the restart comes back in the old language).
- Clearing the whole key-value store in "Delete all data" (
Storage.clearSync(),AsyncStorage.clear()): the settings go with it. Delete through the data layer. - Playing the toggle sound in the row component, or before the dispatch. It sounds twice, and "sound off" still clicks.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/settings-model.md | Homes, fields, defaults, persistence, decoding, actions, effects, iOS and Android, resets, adding a setting, document mode, multi-package, contract keys, checker rules | Workflow steps 1, 5 and 6 |
| references/rows-and-controls.md | Route, model and view; each row kind with VoiceOver and TalkBack; slider pitfall; language list and restart; dialogs; copy keys; testIDs and device flows; tests; React Navigation appendix | Workflow steps 4 and 8 |
templates/src/stores/settings/ |
Schema and defaults, codec, reducer and settings-reducer-cases.ts (the rules as data, also read by state-management-zustand's reducer checker), selectors, store, store context, each with its test (synced canonical copies: never edit here) |
Workflow step 2 |
templates/src/services/settings-storage/ |
SettingsStoragePort and its fake with a test (synced), and the expo-sqlite/kv-store adapter |
Workflow step 2 |
| templates/src/data/open-device-settings.ts | Creates the store over the key-value adapter (composition root) | Workflow steps 2 and 3 |
templates/src/features/settings-effects/ |
PreferencesRoot (language, digits, theme, reduce motion), connectSoundSettings, createHapticsGate, readSavedLanguage (for rtl-and-direction's DirectionGate), with tests |
Workflow step 3 |
templates/src/features/settings/ |
Rows and visibility (with the account group), preference handlers, data-resets.ts ("Delete all data" after its confirmation), the model hook, the language-change plan, with tests |
Workflow step 4 |
templates/src/config/ |
external-links.ts (privacy policy page, store review page per platform, support mail) and its test |
Workflow step 4 |
templates/src/i18n/catalogs/ |
The settings copy keys in en and ar, merged into the app's catalogs |
Workflow step 4 |
templates/contracts/ |
settings.json (the Tasks contract) and settings.schema.json |
Workflow steps 2 and 5 |
| examples/root-layout.tsx | The canonical root layout with the haptics gate and the saved language in decideStartup |
Workflow step 3 |
| examples/app-root.tsx | The canonical AppRoot opening the store, connecting the effects and rendering PreferencesRoot |
Workflow step 3 |
| examples/app-providers.tsx | AppRoot's outer providers with SettingsStoreProvider after the data layer |
Workflow step 3 |
| examples/settings-route.tsx | Thin Expo Router route and its feature hook shape (row hand-offs, the three dialogs) | Workflow step 4 |
| examples/settings-screen.tsx | The pure screen view over the model: rows, failure notes heard on both platforms, confirm dialogs | Workflow step 4 |
| examples/use-settings-input.ts | Where the row facts, locales, layout direction and the data-reset wiring come from | Workflow step 4 |
| examples/settings-contract-document-mode.json | The contract for settings kept in the save document | Workflow step 6 |
scripts/check-settings.mjs |
Checker for the contract, schema, defaults, actions, store, writers, rows, effects, units, resets, restarts and feedback | Workflow step 9, and at the end |
scripts/selftest.mjs |
Proves the checker passes the templates and catches every planted bug | After changing the checker |
scripts/check-lib.mjs |
Shared script helpers, synced from the library (do not edit here) | Never by hand |
scripts/lib/object-literal.mjs |
Shared object-literal reader, synced (do not edit here) | Never by hand |
assets/shared.json |
Declares the synced files (check-lib, the object-literal reader, the canonical store and port files) | When adding a shared file |
assets/template-placeholders.json |
Sample values for the template placeholders (__PRIVACY_POLICY_URL__) used when the templates are verified |
When adding a placeholder |
tests/ |
bases/app/ (a minimal app) and fixtures/ (overlay cases over the templates, including document mode and silent decoys) |
When adding a rule to the checker |
Related skills
state-management-zustand- the store pattern, selectors anduseShallow,updateAndPublish.persistence-and-migrations- the key-value boundary, the save document, data resets.design-system-structure-AppThemeProviderand itspreferenceprop.accessibility-as-code-MotionConfig,useReduceMotion(), roles and targets.i18n-strings-and-catalogs-I18nProvider, language resolution, digits, catalogs.rtl-and-direction- the layout direction and the restart that applies it.audio-and-haptics-feedback- the audio and haptics ports the effects drive.ui-component-library- the row, slider, segmented and dialog components.auth-and-secure-storage- the Sign out and Delete account rows' flows.navigation-and-routing- the settings routes and sub-screens.in-app-purchases,admob-ads-and-consent- the Premium and privacy-choices rows.local-notifications,permissions-and-system-prompts- reminder settings and system settings links.e2e-maestro- the restart flow on named devices.
04 同仓库更多 Skills
demo
Planted skill folder (never scanned).
demo
Planted installed skill (its files must never be scanned).
web-support
Ships the web build of an Expo app: platform files, APIs missing in react-native-web, expo-sqlite headers. Use when adding web, a .web.tsx file or expo export --platform web. Not for responsive layout (adaptive-layout).
value-objects-money-and-units
Stores money as ISO 4217 minor units, quantities in canonical units, instants as epoch ms. Use when adding a price, currency, tax, split, unit or timestamp, or a total is a cent off. Not for calendar days (dates-streaks-and-statistics).
unit-and-component-tests
Sets up Jest, checks unit, component and route tests (RNTL 14, renderWithProviders, SDK mocks, fakes, fast-check, Stryker). Use when writing a test or mock, or Jest fails or flakes. Not for goldens (golden-and-snapshot-tests).
ui-states-and-feedback
Builds loading, empty, failed and offline states, delayed skeletons, toasts, banners, confirms, Undo. Use when a screen loads data, shows a spinner, toast, retry or delete prompt. Not for failure values (error-handling-typed-results).