1k-state-management

OneKey State Management Jotai Atom Organization - MANDATORY STRUCTURE Global State Atoms (for app-wide, persistent state) Location: packages/kit-bg/src/states/jotai/atoms/ Usage: Global settings, account state, hardware state, currency, etc. Pattern: Use globalAtom and EAtomNames for standardization Examples: settings.ts, account.ts, hardware.ts, currency.ts Feature-Specific State Atoms (for localized functionality) Location: packages/kit/src/states/jotai/contexts/[feature_name]/atoms.ts Usage: Feature-specific state that may be shared across components within that feature Pattern: Use contextAtom from createJotaiContext for consistency Structure: contexts/ ├── marketV2/ │ ├── atoms.ts - State definitions │ ├── actions.ts - State operations │ └── index.ts - Exports ├── swap/ │ ├── atoms.ts │ ├── actions.ts │ └── index.ts

FORBIDDEN Atom Patterns ❌ NEVER create atom directories under packages/kit/src/views/ ❌ NEVER create standalone atom files in component directories ❌ NEVER mix globalAtom and contextAtom patterns without architectural justification Atom Selection Guidelines Use globalAtom when: State needs persistence across app restarts State is used across multiple major features State affects the entire application (settings, authentication, etc.) Located in packages/kit-bg/src/states/jotai/atoms/ Use contextAtom when: State is specific to a feature or module State is temporary/session-based State is shared within related components of a feature Located in packages/kit/src/states/jotai/contexts/[name]/atoms.ts

IMPORTANT: These are the ONLY two atom patterns used in the project. Do not create custom atom patterns or use plain Jotai atoms outside of these established structures.

Common Patterns Creating a Global Atom // packages/kit-bg/src/states/jotai/atoms/myFeature.ts import { globalAtom } from '../utils'; import { EAtomNames } from '../atomNames';

export const myFeatureAtom = globalAtom({ name: EAtomNames.myFeature, initialValue: { / initial state / }, persist: true, // if persistence needed });

Creating a Context Atom // packages/kit/src/states/jotai/contexts/myFeature/atoms.ts import { createJotaiContext } from '../../utils';

const { contextAtom, useContextAtom } = createJotaiContext();

export const myFeatureDataAtom = contextAtom(null);

// Export hook for components export { useContextAtom };

Using Atoms in Components import { useAtom, useAtomValue, useSetAtom } from 'jotai'; import { myFeatureAtom } from '@onekeyhq/kit-bg/src/states/jotai/atoms';

function MyComponent() { // Read and write const [value, setValue] = useAtom(myFeatureAtom);

// Read only const value = useAtomValue(myFeatureAtom);

// Write only const setValue = useSetAtom(myFeatureAtom); }