Back to Details

dexiejs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dexie.js

Dexie.js

Implement Dexie as a production data layer, not as scattered table calls inside UI components.

将Dexie实现为生产级数据层，而非在UI组件中分散调用数据表。

Workflow

工作流程

Classify runtime and rendering mode

Confirm whether the target code runs only in browser or can run on server too.
Prevent Dexie usage on server runtimes in Next.js, TanStack Start, and SvelteKit.
Load
```
references/framework-integration.md
```
before writing framework-specific code.

Design schema from query shapes

List read queries first (filters, sorts, ranges), then derive indexes.
Use compound and multi-entry indexes when queries require them.
Keep key strategy explicit (
```
++id
```
, custom IDs, or compound primary key).
Load
```
references/core-patterns.md
```
sections 2 and 3.

Implement one shared DB module

Define Dexie instance once per app/package.
Export typed table handles and data-layer helper functions.
Keep transaction boundaries in the data layer.

Add reactive reads

Use
```
liveQuery()
```
for framework-agnostic reactivity.
In React, prefer
```
useLiveQuery
```
from
```
dexie-react-hooks
```
.
In Svelte, consume
```
liveQuery
```
observables directly in components.

Add writes with invariants

Use
```
db.transaction()
```
for multi-table consistency and read-modify-write logic.
Avoid unrelated async APIs inside transactions unless deliberately wrapped with
```
Dexie.waitFor()
```
.

Plan upgrades before release

Add new versions with
```
db.version(n).stores(...).upgrade(...)
```
.
Make migration code idempotent and safe for partially-updated datasets.

Validate behavior

Test cold start, reload persistence, and multi-tab updates.
Test migration from previous schema with realistic data.
Verify SSR/client boundaries are enforced in hybrid frameworks.

分类运行时与渲染模式

确认目标代码仅在浏览器运行还是也可在服务器运行。
避免在Next.js、TanStack Start和SvelteKit的服务器运行时中使用Dexie。
在编写框架特定代码前，加载
```
references/framework-integration.md
```
。

从查询形态设计模式

先列出读取查询（过滤器、排序、范围），再推导索引。
当查询需要时，使用复合索引和多条目索引。
明确键策略（
```
++id
```
、自定义ID或复合主键）。
加载
```
references/core-patterns.md
```
的第2和第3部分。

实现一个共享数据库模块

每个应用/包仅定义一次Dexie实例。
导出带类型的数据表句柄和数据层辅助函数。
将事务边界保留在数据层中。

添加响应式读取

使用
```
liveQuery()
```
实现框架无关的响应式。
在React中，优先使用
```
dexie-react-hooks
```
中的
```
useLiveQuery
```
。
在Svelte中，直接在组件中使用
```
liveQuery
```
可观察对象。

添加带有不变量的写入操作

使用
```
db.transaction()
```
确保多表一致性以及读取-修改-写入逻辑。
除非特意用
```
Dexie.waitFor()
```
包装，否则避免在事务中使用无关的异步API。

发布前规划升级

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

验证行为

测试冷启动、重载持久性和多标签页更新。
使用真实数据测试从旧模式到新模式的迁移。
验证混合框架中的SSR/客户端边界是否得到严格执行。

Framework Routing

框架路由

Vanilla JS: shared DB module +
```
liveQuery().subscribe(...)
```
.
React:
```
dexie-react-hooks
```
+ colocated data hooks.
Next.js: client boundaries (
```
'use client'
```
) or dynamic import with
```
ssr: false
```
.
TanStack Start: treat loaders as isomorphic; gate Dexie with
```
createClientOnlyFn
```
.
Svelte/SvelteKit: use
```
liveQuery
```
; in SvelteKit gate with
```
$app/environment
```
(
```
browser
```
).

Load

references/framework-integration.md

for templates.

Vanilla JS：共享数据库模块 +
```
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

获取模板。

Output Contract

输出约定

When using this skill, return:

Runtime boundary strategy and why.
Final schema and index rationale per query path.
Data-layer API surface (read/write helpers and transaction rules).
Reactive read strategy for the selected framework.
Migration plan and rollback considerations.
Remaining risks and targeted tests.

使用此技能时，需返回：

运行时边界策略及其原因。
每个查询路径的最终模式和索引设计依据。
数据层API接口（读取/写入辅助函数和事务规则）。
针对所选框架的响应式读取策略。
迁移计划和回滚注意事项。
剩余风险和针对性测试方案。

References

参考资料

```
references/core-patterns.md
```
Core Dexie patterns: schema syntax, CRUD/query, transactions, migrations, reactivity, and performance.
```
references/framework-integration.md
```
Framework implementations for Vanilla JS, React, Next.js, TanStack Start, Svelte, and SvelteKit.
```
references/troubleshooting.md
```
Symptom-to-fix guide for SSR boundary leaks, stale live queries, transaction issues, and migration failures.

```
references/core-patterns.md
```
核心Dexie模式：模式语法、CRUD/查询、事务、迁移、响应式和性能。
```
references/framework-integration.md
```
适用于Vanilla JS、React、Next.js、TanStack Start、Svelte和SvelteKit的框架实现方案。
```
references/troubleshooting.md
```
针对SSR边界泄漏、实时查询过期、事务问题和迁移失败的症状-修复指南。