From e64a3cecd57145d0aaef9b78b4806832d1f9559e Mon Sep 17 00:00:00 2001
From: afc163 <afc163@gmail.com>
Date: Thu, 7 May 2026 21:00:24 +0800
Subject: [PATCH] fix: enable valtio plugin and add documentation

Enable `valtio: {}` in config so `proxy`, `useSnapshot`, and other
valtio APIs are available from `@umijs/max`. Without this config,
valtio imports from `@umijs/max` return undefined (fixes #11772).

Also add valtio usage guide to both zh-CN and en-US cheatsheets
and update CLAUDE.md state management section.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CLAUDE.md                |  1 +
 config/config.ts         |  6 ++++++
 docs/cheatsheet.en-US.md | 20 ++++++++++++++++++++
 docs/cheatsheet.zh-CN.md | 20 ++++++++++++++++++++
 4 files changed, 47 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index ee40aa3f..4f7206ac 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,6 +88,7 @@ Umi Max (`@umijs/max`) is the meta-framework. It wraps the build pipeline and pr
 - **`useModel('@@initialState')`** for global state (currentUser, settings). Initialized by `getInitialState()` in `app.tsx` which runs once on app startup
 - **`useRequest`** from `@umijs/max` for simple data fetching
 - **@tanstack/react-query** for complex server state (e.g., table-list uses `useMutation` + `useQuery`)
+- **Valtio** (`proxy`, `useSnapshot`): proxy-based reactive state for fine-grained updates. Import from `@umijs/max`. Create stores with `proxy()` at module level, read with `useSnapshot()` in components
 - Most pages use ProTable's built-in `request` prop for data loading
 
 ### Styling Systems
diff --git a/config/config.ts b/config/config.ts
index c0ba6394..0094d085 100644
--- a/config/config.ts
+++ b/config/config.ts
@@ -173,6 +173,12 @@ export default defineConfig({
    * @doc https://umijs.org/docs/max/access
    */
   access: {},
+  /**
+   * @name Valtio 插件
+   * @description 基于 valtio 的状态管理方案
+   * @doc https://umijs.org/docs/max/valtio
+   */
+  valtio: {},
   /**
    * @name Google Analytics
    * @description 使用 GA4 (gtag.js) 进行站点分析
diff --git a/docs/cheatsheet.en-US.md b/docs/cheatsheet.en-US.md
index 9ea85058..fa38726a 100644
--- a/docs/cheatsheet.en-US.md
+++ b/docs/cheatsheet.en-US.md
@@ -234,6 +234,26 @@ const mutation = useMutation({
 });
 ```
 
+**Valtio — reactive state management:** Proxy-based reactive state for fine-grained updates:
+
+```ts
+// Create store (can be at module level in any file)
+import { proxy, useSnapshot } from '@umijs/max';
+
+export const settingsStore = proxy({
+  theme: 'light' as 'light' | 'dark',
+  sidebarCollapsed: false,
+});
+
+// Use in components
+function ThemeToggle() {
+  const snap = useSnapshot(settingsStore);
+  return <button onClick={() => { settingsStore.theme = snap.theme === 'light' ? 'dark' : 'light'; }}>
+    Current theme: {snap.theme}
+  </button>;
+}
+```
+
 **Initial state — getInitialState:** Define in `src/app.tsx`, accessible globally:
 
 ```tsx
diff --git a/docs/cheatsheet.zh-CN.md b/docs/cheatsheet.zh-CN.md
index 8ff9b7c5..8abfc58b 100644
--- a/docs/cheatsheet.zh-CN.md
+++ b/docs/cheatsheet.zh-CN.md
@@ -234,6 +234,26 @@ const mutation = useMutation({
 });
 ```
 
+**Valtio — 响应式状态管理：** 基于 proxy 的响应式状态，适合需要细粒度更新的场景：
+
+```ts
+// 创建 store（可在任意文件中，模块级别直接调用）
+import { proxy, useSnapshot } from '@umijs/max';
+
+export const settingsStore = proxy({
+  theme: 'light' as 'light' | 'dark',
+  sidebarCollapsed: false,
+});
+
+// 组件中使用
+function ThemeToggle() {
+  const snap = useSnapshot(settingsStore);
+  return <button onClick={() => { settingsStore.theme = snap.theme === 'light' ? 'dark' : 'light'; }}>
+    当前主题: {snap.theme}
+  </button>;
+}
+```
+
 **初始状态 — getInitialState：** 在 `src/app.tsx` 中定义，全局可访问：
 
 ```tsx