dexiejs

Dexie.js

将 Dexie 实现为生产级数据层，而不是在 UI 组件中零散地调用表。

工作流

1. 确定运行时和渲染模式

• 确认目标代码是否仅在浏览器中运行，还是也可能在服务器上运行。
• 在 Next.js、TanStack Start 和 SvelteKit 中，禁止在服务器运行时使用 Dexie。
• 编写框架专用代码前，先加载 references/framework-integration.md。

2. 根据查询形态设计架构

• 先列出读取查询（筛选、排序、范围），再据此推导索引。
• 查询有需要时使用复合索引和多入口索引。
• 明确主键策略（++id、自定义 ID 或复合主键）。
• 加载 references/core-patterns.md 第 2 和第 3 节。

3. 实现一个共享 DB 模块

• 每个应用／包只定义一次 Dexie 实例。
• 导出带类型的表句柄和数据层辅助函数。
• 在数据层中管理事务边界。

4. 添加响应式读取

• 使用 liveQuery() 实现与框架无关的响应式。
• 在 React 中，优先使用 dexie-react-hooks 中的 useLiveQuery。
• 在 Svelte 中，直接在组件内使用 liveQuery observables。

5. 添加带不变量保障的写入

• 对于多表一致性和读取—修改—写入逻辑，使用 db.transaction()。
• 避免在事务中调用无关的异步 API，除非有意使用 Dexie.waitFor() 封装。

6. 在发布前规划升级

• 使用 db.version(n).stores(...).upgrade(...) 添加新版本。
• 确保迁移代码具有幂等性，并能安全处理仅部分更新的数据集。

7. 验证行为

• 测试冷启动、重新加载后的持久化，以及多标签页更新。
• 使用真实数据测试从先前架构迁移。
• 验证混合框架中的 SSR／客户端边界是否得到强制执行。

框架路由

• Vanilla JS：共享 DB 模块 + liveQuery().subscribe(...)。
• React：dexie-react-hooks + 就近定义的数据钩子。
• Next.js：客户端边界（'use client'）或使用 ssr: false 的动态导入。
• TanStack Start：将加载器视为同构代码；使用 createClientOnlyFn 限制 Dexie 的使用范围。
• Svelte／SvelteKit：使用 liveQuery；在 SvelteKit 中通过 $app/environment（browser）进行限制。

加载 references/framework-integration.md 获取模板。

输出约定

使用此技能时，返回：

• 运行时边界策略及原因。
• 最终架构，以及每种查询路径的索引设计依据。
• 数据层 API 表面（读写辅助函数和事务规则）。
• 所选框架的响应式读取策略。
• 迁移计划和回滚注意事项。
• 剩余风险和有针对性的测试。

参考资料

• references/core-patterns.md Dexie 核心模式：架构语法、CRUD／查询、事务、迁移、响应式和性能。

• references/framework-integration.md Vanilla JS、React、Next.js、TanStack Start、Svelte 和 SvelteKit 的框架实现。

• references/troubleshooting.md 针对 SSR 边界泄漏、实时查询过时、事务问题和迁移失败的症状—修复指南。