ahooks-v3_skill

Overview

This skill provides concise guidance for using ahooks v3+ utility hooks for React state management, focusing on grouped state updates and localStorage persistence. It explains when to pick useSetState vs useLocalStorageState and how they fit with URL state and async patterns. The goal is practical recommendations for React 18+ projects using TypeScript.

How this skill works

It inspects common state scenarios and recommends the appropriate hook: useSetState for shallow-merged grouped state updates, and useLocalStorageState for values that must persist across browser sessions. It also describes integration patterns (bidirectional sync) with URL state managers like nuqs and clarifies what to avoid (loading/error states and complex async flows).

When to use it

• Grouped state that changes together (forms, UI panels, game state) → useSetState
• State that must persist across sessions (preferences, toggles) → useLocalStorageState
• When you need type safety with TypeScript generics for stored values
• When syncing shareable flags between URL and storage (use bidirectional sync with nuqs)
• Avoid for async loading/error state or complex state machines — use TanStack Query instead

Best practices

• Use useSetState for partial, shallow-merged updates instead of many individual useState hooks
• Use useLocalStorageState<T>('key', { defaultValue }) with TypeScript generics for type-safe persistence
• Prefer nuqs for URL-shareable state and keep localStorage for non-URL persistence or explicit sync scenarios
• Don’t store sensitive data in localStorage; avoid mixing URL and storage without explicit sync logic
• Use TanStack Query for data fetching, caching, and loading/error state rather than ahooks hooks

Example use cases

• Form editor where multiple fields update together → useSetState for concise partial updates
• User theme, font size, or debug flags persisted across reloads → useLocalStorageState
• Feature toggle that should be both URL-shareable and persistent → sync nuqs query state with useLocalStorageState
• Ephemeral UI state like panel visibility or in-memory game level state → useSetState
• Preferences with strict TypeScript types (Settings object) → useLocalStorageState<Settings>('settings', { defaultValue })