Fireproof 数据库 API

Fireproof 是一款轻量级的嵌入式文档数据库，具备加密的实时同步功能，专为简化浏览器应用开发而设计。它采用统一的 API，可在任何 JavaScript 环境中使用，既支持 React（配合 hooks），也作为独立的核心 API 运行。

将这些文档提供给 Point AI 的开发者。

核心特性

• 应用随处运行： 将 UI、数据和逻辑打包到一个文件中。
• 实时与离线优先： 自动持久化和实时查询，在浏览器中直接运行，无需加载或错误状态。
• 统一 API： TypeScript 兼容 Deno、Bun、Node.js 和浏览器。
• React Hooks： 利用 useLiveQuery 和 useDocument 实现实时协作。

Fireproof 通过哈希历史记录强制执行加密的因果一致性与账本完整性，提供类似 Git 的版本控制，并结合轻量级区块链式的验证机制。数据以内容寻址的加密 Blob 形式存储和复制，从而确保安全，并可轻松通过通用对象存储服务提供商进行同步。

安装

use-fireproof 包同时提供了核心 API 和 React hooks：

npm install use-fireproof

也可与 ⚡️ ESM.sh 配合使用：

import { useFireproof } from "https://esm.sh/use-fireproof";

或者在任意 JavaScript 环境中安装核心账本：

npm install @fireproof/core

还可以通过 HTML <script> 标签将账本添加到任何网页中（全局变量为 Fireproof）：

<script src="https://cdn.jsdelivr.net/npm/@fireproof/core/dist/browser/fireproof.global.js"></script>

生成的解决方案可通过 ChatGPT Canvas、v0、bolt.new 或 Claude Artifacts 作为可运行的微型应用交付。只需将代码粘贴到此处即可部署带有 React 和 Tailwind 的单页应用：https://codepen.io/useFireproof/pen/MYgNYdx

⚛️ React 使用

在 LLM 代码生成场景中，推荐使用 React hooks 来操作 Fireproof：

import { useFireproof } from "use-fireproof";

function App() {
  const { database, useLiveQuery, useDocument } = useFireproof("my-ledger");

  // 使用 useDocument 创建新文档
  const { doc, merge, submit } = useDocument({ text: "" });

  // 按 _id 查询文档，按最新时间排序
  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });

  return (
    <div>
      <form onSubmit={submit}>
        <input value={doc.text} onChange={(e) => merge({ text: e.target.value })} placeholder="新文档" />
        <button type="submit">提交</button>
      </form>

      <h3>最近文档</h3>
      <ul>
        {docs.map((doc) => (
          <li key={doc._id}>{doc.text}</li>
        ))}
      </ul>
    </div>
  );
}

阅读 逐步 React 教程，快速上手；或查看 完整 LLM 文档，获取更多示例。

图片处理

Fireproof 让你在应用中轻松存储和展示图片。借助 _files 属性和 ImgFile 组件，可以处理文件存储与检索的所有复杂性：

// 从文件输入框中存储图片
function handleFileUpload(e) {
  if (e.target.files[0]) {
    merge({
      _files: { profilePic: e.target.files[0] },
      uploadedAt: new Date().toISOString(),
    });
  }
}

// 从文档中显示图片
function ImageDisplay({ doc }) {
  return (
    <div>
      {doc._files?.profilePic && (
        <ImgFile file={doc._files.profilePic} alt="头像" onLoad={() => console.log("图片已加载")} />
      )}
      <p>上传时间：{doc.uploadedAt}</p>
    </div>
  );
}

ImgFile 组件会自动处理 Fireproof 存储中的图片加载与显示，具备标准 <img> 元素的所有属性。更多深入示例请参阅我们的 llms-full.txt 文档。

JavaScript 核心 API

对于熟悉其他文档数据库的用户来说，Fireproof 的文档数据库 API 应该会非常直观：

import { fireproof } from "@fireproof/core";

const db = fireproof("music-app");

await db.put({ _id: "beyonce", name: "Beyoncé", hitSingles: 29 });

db.subscribe(async () => {
  const topArtists = await db.query("hitSingles", { range: [30, Infinity] });
  // 使用新的顶级艺人重新渲染 UI
});

const beyonceDoc = await db.get("beyonce");
beyonceDoc.hitSingles += 1;
await db.put(beyonceDoc);

为什么选择 Fireproof

与其他嵌入式数据库相比，Fireproof：

• 具备网络感知能力、加密保护及多写者安全性；
• 专为基于 CRDT 的实时协作而设计；
• 为所有操作提供加密的因果完整性；
• 面向 Web 构建，包体积小且无需 WebAssembly。

无需等待后端即可交付交互式体验。Fireproof 可在任何云、浏览器或边缘环境中运行，因此你的应用可以在任何地方访问数据。

使用场景

Fireproof 特别适用于以下场景：

• AI 生成的应用和快速原型；
• 协作编辑；
• 离线优先与本地优先的应用；
• 个性化与配置管理；
• AI 助理的安全性。

借助 Fireproof，你可以先快速搭建应用，待准备就绪后再通过你选择的云服务进行同步，非常适合 LLM 代码生成场景和快速开发。

在我们的博客上获取最新的路线图更新 或加入我们的 Discord 进行协作。阅读文档了解更多关于 架构 的信息。

调试

要控制日志输出，可以使用 FP_DEBUG 环境变量，或在代码中设置调试级别：

FP_DEBUG='*' node myapp.js

logger.setDebug(...moduleNameList 或 '*')

如果你在浏览器中，可以使用以下代码来设置调试级别：

this[Symbol.for("FP_ENV")].set("FP_DEBUG", "*");

// vitest 传递环境变量
globalThis[Symbol.for("FP_PRESET_ENV")] = {
  FP_DEBUG: "*",
};

测试

要在所有项目中运行完整的测试套件（已测试的存储网关配置），请运行：

pnpm run test

要针对特定组件或模块运行测试，请使用以下命令模式：

pnpm run test -t '测试名称模式' 测试文件路径

例如，仅在一个项目中为 CRDT 模块运行特定测试：

FP_DEBUG='Loader,CRDTClock' pnpm run test --project file -t 'codec implict iv' crdt

对于 React 组件的测试，可以使用：

pnpm run test tests/react/[ComponentName].test.tsx

以测试 ImgFile 组件为例：

pnpm run test tests/react/ImgFile.test.tsx

日志格式化

可以通过设置 FP_FORMAT 来更改日志格式：

• jsonice 会将日志输出为多行 JSON 格式。
• yaml 会将日志输出为 YAML 格式。
• json 会将日志输出为单行 JSON 格式（默认）。

KeyBag

如果在 FP_STORAGE_URL URL 中添加 extractKey 参数，并将其值设置为 _deprecated_internal_api，则可以绕过安全检查以提取密钥材料。这是默认配置，但使用此功能时会发出警告，并且未来计划实现更安全的密钥管理方案。

Deno

Fireproof 与 Deno 兼容。要在 Deno 中运行，需要添加以下标志：

目前尚未使用 Deno 运行测试——待办事项。

使用我们提供的 deno.json 文件可能会有些奇怪——待办事项是将 Fireproof 添加到 jsr 和 deno.land。

deno run --config node_modules/@fireproof/core/deno.json --allow-read --allow-write --allow-env --unstable-sloppy-imports ./node-test.ts

创建文档

请注意，这将直接推送。

pnpm run build:docs

感谢 🙏

Fireproof 是多年来网络社区中各位同仁共同努力的结晶。我甚至无法一一列举所有做出关键贡献的人。如果没有 npm、React 和 VS Code，这一切都会花费更多的时间。感谢所有通过 Apache CouchDB——最早的文档账本之一——支持我进入账本开发领域的人。我们在不可变数据结构方面的独特工作，得益于对 IPFS、IPLD 以及 Filecoin APIs 多年来的深入思考。

感谢 Meno Abels，他担任了项目的首席工程师。Fireproof 正在迅速发展成为一个成熟的解决方案。

还要感谢 Alan Shaw 和 Mikeal Rogers，没有他们，这个项目根本不可能启动。核心的 Merkle 哈希树时钟基于 Alan 的 Pail，而仓库的历史可以追溯到该仓库的一个分支。Mikeal 编写了 prolly 树的实现。

贡献

我们非常欢迎贡献。欢迎随时加入 Discord 上的讨论，所有人皆可参与。Discord 邀请链接

许可证

采用双许可协议，即 MIT 或 Apache 2.0

Fireproof 快速上手指南

Fireproof 是一个轻量级的嵌入式文档数据库，支持加密实时同步，专为浏览器应用设计。它具备离线优先、实时协作和统一 API 特性，适用于 React、Node.js、Deno 等多种 JavaScript 环境。

环境准备

• 系统要求：支持任何现代浏览器、Node.js、Deno 或 Bun 环境。
• 前置依赖：
  • Node.js (推荐 v18+) 或现代浏览器
  • npm、pnpm 或 yarn 包管理器
  • 若使用 React，需安装 React 18+

安装步骤

方式一：安装完整包（含 React Hooks）

npm install use-fireproof

方式二：仅安装核心库（适用于非 React 项目）

npm install @fireproof/core

方式三：通过 CDN 直接在 HTML 中使用

<script src="https://cdn.jsdelivr.net/npm/@fireproof/core/dist/browser/fireproof.global.js"></script>

方式四：使用 ESM.sh（无需安装）

import { useFireproof } from "https://esm.sh/use-fireproof";

💡 国内开发者如遇网络问题，可尝试使用镜像源：

npm config set registry https://registry.npmmirror.com

基本使用

React 项目示例（推荐）

import { useFireproof } from "use-fireproof";

function App() {
  const { database, useLiveQuery, useDocument } = useFireproof("my-ledger");

  // 创建或编辑文档
  const { doc, merge, submit } = useDocument({ text: "" });

  // 查询最新 100 条文档
  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });

  return (
    <div>
      <form onSubmit={submit}>
        <input 
          value={doc.text} 
          onChange={(e) => merge({ text: e.target.value })} 
          placeholder="输入内容" 
        />
        <button type="submit">提交</button>
      </form>

      <h3>最近文档</h3>
      <ul>
        {docs.map((doc) => (
          <li key={doc._id}>{doc.text}</li>
        ))}
      </ul>
    </div>
  );
}

纯 JavaScript / Node.js 示例

import { fireproof } from "@fireproof/core";

const db = fireproof("music-app");

// 写入文档
await db.put({ _id: "beyonce", name: "Beyoncé", hitSingles: 29 });

// 订阅数据变化
db.subscribe(async () => {
  const topArtists = await db.query("hitSingles", { range: [30, Infinity] });
  console.log("热门艺术家:", topArtists);
});

// 读取并更新文档
const beyonceDoc = await db.get("beyonce");
beyonceDoc.hitSingles += 1;
await db.put(beyonceDoc);

图片上传与展示

// 上传图片
function handleFileUpload(e) {
  if (e.target.files[0]) {
    merge({
      _files: { profilePic: e.target.files[0] },
      uploadedAt: new Date().toISOString(),
    });
  }
}

// 展示图片
function ImageDisplay({ doc }) {
  return (
    <div>
      {doc._files?.profilePic && (
        <ImgFile file={doc._files.profilePic} alt="头像" />
      )}
      <p>上传时间：{doc.uploadedAt}</p>
    </div>
  );
}

Fireproof 自动处理文件存储、加密与同步，开发者只需关注业务逻辑。