Bareship 为移动应用预置离线写入机制

Bareship 想解决的，是 React Native 项目跑出第一个页面之后的麻烦：断网操作会不会丢、登录令牌存在哪、目录边界能不能守住，以及 AI 写代码时是否遵守同一套规则。它把这些决定预先装进了一个免费、MIT 许可的模板。

作者的主张很明确：基础设施应该少重复造，团队约定应该交给工具执行。对准备启动移动端项目的前端和全栈开发者，这套思路值得看，但「离线只生效一次」和「可用于生产」都需要继续检查实现细节。

离线优先，先决定每次写入怎么办

Bareship 基于 bare React Native 0.87，面向 iOS 和 Android。作者反复遇到的问题是，每个新项目都要花一到两周重建基础设施，缺口往往等到用户网络变差才暴露。

它要求每次写入明确选择四种离线处理模式之一。不过，原文只展开了排队写入，没有解释另外三种，不能据此推断所有操作都适合自动同步。

排队写入会先落盘，应用重启后仍然保留，恢复网络后按操作顺序重放。页面标题下方的横幅会显示待同步变更数量，让用户知道操作还在等待处理。没有选择处理模式的写入，离线时直接失败，避免误入队列。

这里最关键的是幂等键（idempotency key）：同一次写入的所有发送尝试，都携带同一个标识，供接收端识别重复请求。

请求可以重复发送，业务变更只应用一次，才是这里要解决的问题。

但客户端保存标识，还不足以独立保证这个结果。接入真实后端后，服务端也得配合去重。原文没有交代去重记录如何保存、保留多久，以及多端同时编辑如何处理冲突，这些需要另外验证。

目录约定为什么要写进检查工具

作者担心的另一件事，是第一周约定的目录结构，到了第六个月，经过三名开发者和一个编码 Agent 持续修改，还剩下多少。

Bareship 用 ESLint 和 dependency-cruiser 执行架构规则：层之间只能向下导入，功能模块不能访问彼此内部文件，界面文本必须经过翻译系统，无障碍属性统一使用一套 ARIA props。违反规则就无法通过检查。

这比只在文档里写「请保持模块独立」更具体。开发者和 AI 都能在修改时收到反馈，代码审查也能少花时间重复指出同类问题。规则不适合项目时，可以集中修改，并通过架构决策记录（ADR）留下原因。

给 AI 的上下文也沿用这套安排。仓库提供 AGENTS.md、ADR 和 React Native agent skills，并通过 pnpm gen feature | screen | endpoint 生成 schema、API hooks、mock、翻译字符串和测试，让新增代码遵循已有结构。

作者表示，Bareship 的大量代码由 Claude Code 辅助完成。这些约束从开发初期就在 Agent 上使用；发现它违反规则，就把修正放进 linter 或 AGENTS.md。

这是作者的实际使用经历。但原文没有给出 Claude Code、Cursor、Copilot 之间的对照结果，也没有统计违规率，不能进一步推导出它能稳定约束所有 Agent。

不接后端就能跑，但首次构建仍有成本

开发构建内置 mock 后端，可以先登录、浏览信息流和测试离线模式，不必提前准备真实后端、Firebase 项目或 Apple 账户。这个承诺的范围是先启动和体验应用，不能据此推断后续真机签名、发布等环节也无需账户。

Crashlytics、Analytics、Remote Config 和推送，在加入 Firebase 配置文件后启用；缺少配置时退回日志输出。登录令牌从一开始就存进 Keychain 和 Keystore。

模板还带有明暗主题、英语和印地语、可开启的从右向左布局，以及深度链接、强制更新和维护页面。环境分为 dev、staging、prod，并提供 fastlane 发布流程和可安装的演示构建。

下面这组命令负责创建并运行项目：

npx create-bareship Acme
cd Acme
pnpm android   # or: pnpm ios

要留意最后一行：运行平台可以选择，但原生构建成本依然存在。create-bareship 会先检查工具，询问 bundle id 和显示名称，安装依赖并创建首次提交。

作者演示中，创建应用实际耗时 1 分 15 秒。首次 Android 构建需要编译原生库，在其 8 GB M1 上约 20 分钟，更快的机器需要几分钟，后续构建则较快。这组数据是作者设备上的体验，不能直接当成团队的工期估算。

我的判断

我认同它把离线写入、架构约束和 Agent 指令一起设计。相比只有登录页和导航的 starter，这些内容更接近项目长期维护时会反复遇到的问题。尤其是把可机械检查的约定交给工具，方向很实用。

代价是接手一整套预设。已有稳定工程规范的团队，需要比较迁移和改造成本；只想验证交互的项目，也未必需要立即引入全部配套能力。

原文所述版本为 0.3.2，而且恢复仓库 CI 仍在待办列表里。

因此，「production-ready」目前应当作为作者的定位来看。原文没有提供生产规模、故障恢复或对照测试数据，「省下一周」也只是经验预期。是否适合上线，仍要看队列实现、后端协议和自动化检查能否满足自己的业务。

能拿来做什么

• 启动 React Native 项目前，先用演示流程检查离线写入：断网操作、退出重启、重新联网，观察数据和待同步数量是否一致。
• 接入真实 API 时，把幂等键写进前后端协议，并验证重复请求的结果；编辑冲突需要单独设计处理策略。
• 在日常 AI 编程中，把目录边界、翻译要求等可检查规则放进工具，把原因和使用方式写进 AGENTS.md、ADR，减少反复口头纠正。
• 选用模板前，在团队设备上实跑创建、首次构建和现有检查流程，结合 0.3.2 的完成度判断接入成本。