react-native-hox

面向 React Native 的轻量状态管理方案：类型安全、API 极简，支持组件内 Hook 与组件外 Vanilla 读写，并内置可选持久化能力。


快速开始

$3

``bash
npm i react-native-hox
`

$3

`ts
// stores/user.ts
import { createModel } from 'react-native-hox';

export const userStore = createModel({ name: 'Guest' }); // 数据只存在内存
// export const userStore = createModel({ name: 'Guest' }, { persist: 'user_v1' }); // 数据存在缓存 AsyncStorage
`

`tsx
// Profile.tsx
import React from 'react';
import { View, Text, Button } from 'react-native';
import { userStore } from './stores/user';

export function Profile() {
const user = userStore.getState();
return (

Hello, {user.name}
userStore.setState({ name: 'Tom' })} />

);
}
`

功能点

$3

`ts
import { createModel } from 'react-native-hox';

export const profileStore = createModel({ name: 'Guest', role: 'user' as 'user' | 'admin' });
`

`tsx
import React from 'react';
import { View, Text, Button } from 'react-native';
import { profileStore } from './stores/profile';

export function UpdateExample() {
const profile = profileStore.getState();

return (

{profile.name}
{profile.role}


profileStore.setState({ name: 'Alice' })} />
profileStore.setState({ name: 'Bob', role: 'admin' }, true)} />

);
}
`

$3

`ts
import { createModel } from 'react-native-hox';

export const counterStore = createModel({ count: 0, text: 'a' });
`

`tsx
import React from 'react';
import { View, Text, Button } from 'react-native';
import { counterStore } from './stores/counter';

export function SelectorExample() {
const count = counterStore.getState((s) => s.count);

return (

{count}


counterStore.setState((s) => ({ count: s.count + 1 }))} />
counterStore.setState({ text: String(Math.random()) })} />

);
}
`

当 selector 返回对象/数组时，传入 equalityFn（例如 shallow）避免无意义重渲染：

`tsx
import { shallow } from 'react-native-hox';
import { counterStore } from './stores/counter';

const picked = counterStore.getState((s) => ({ count: s.count }), shallow);
`

$3

`ts
import { userStore } from './stores/user';

const name1 = userStore.data.state.name;
const name2 = userStore.data.getState().name;

const unsub = userStore.data.subscribe((next, prev) => {
console.log(next, prev);
});
unsub();
`

$3

只要提供一个 key 即可开启持久化（默认使用 @react-native-async-storage/async-storage，无需重复传 storage）：

`ts
import { createModel } from 'react-native-hox';

export const authStore = createModel({ token: '' }, { persist: 'auth_v1' });
`

如果你希望替换存储引擎，可以在 persist.storage 传入实现同等接口的存储对象：

`ts
import { createModel } from 'react-native-hox';
import type { StorageEngine } from 'react-native-hox';

const storage: StorageEngine = {
getItem: async (key) => null,
setItem: async (key, value) => {},
removeItem: async (key) => {},
};

export const authStore = createModel({ token: '' }, { persist: { key: 'auth_v1', storage } });
`

$3

`ts
import { userStore } from './stores/user';

userStore.reset();
userStore.destroy();
`

`ts
import { createModel } from 'react-native-hox';

export const strictStore = createModel(
{ count: 0 },
{ strict: { forbidSetStateAfterDestroy: true } }
);
`

进阶使用

$3

`tsx
import React, { useEffect } from 'react';
import { View, Text } from 'react-native';
import { userStore } from './stores/user';

export function SubscribeExample() {
const name = userStore.getState((s) => s.name);

useEffect(() => {
const unsub = userStore.data.subscribe(
(s) => s.name,
(next, prev) => {
console.log('name changed:', prev, '->', next);
},
{ fireImmediately: true }
);
return unsub;
}, []);

return (

{name}

);
}
`

$3

`ts
import { createModel } from 'react-native-hox';

export const userPersistStore = createModel(
{ token: '', isLogin: false },
{
persist: {
key: 'user_v1',
beforeRecover: (v) => ({
token: v?.token ?? '',
isLogin: Boolean(v?.token),
}),
},
}
);
`

$3

`ts
import { createModel } from 'react-native-hox';

export const appStore = createModel(() => ({ bootAt: Date.now() }));
`

API 参考（简版）

$3

- initialState: T 或 () => T
- options.persist: string 或 { key, storage?, debounce?, beforePersist?, beforeRecover? }
- options.strict.forbidSetStateAfterDestroy: boolean
- options.logger: { warn, error }

返回的 Model 同时支持：

- 组件内（Hook）：model.getState() / model.use() / model.useState()
- 组件外（Vanilla）：model.data.state / model.data.getState() / model.data.setState() / model.data.subscribe()`

License

ISC