| name | create-app |
| description | 从零创建一款生产级移动应用（Expo/React Native 独立仓库）。沉淀自一个成熟上架应用的架构经验：pnpm monorepo + Expo Router + 主题 token 单源 + zustand/MMKV/SQLite 数据层 + 可选 Supabase auth/sync/payments/i18n/观测。Use when the user asks to 创建一款新应用 / 新 app / 起一个新项目 / scaffold a new mobile app / create-app. |
create-app — 生产级移动应用脚手架
本 skill 沉淀的是经验、规范、模式与架构选型，不是代码库：所有决策都在真实上架应用（iOS/Android 双端、App Store + Google Play + 自分发三渠道）中经过生产验证。产出物 = 一个全新的独立 monorepo 仓库。
版本基线：Expo SDK 57 / RN 0.86 / React 19.2 / TS 6.0（2026-07 校准）。搭建时用 npx expo install 解析实际版本，不要硬编码本 skill 中出现的版本号；SDK 升级时的核对清单见 references/05-cross-cutting.md §9。
工作流
Step 0 — 收集参数（一次问齐，再动手）
| 参数 | 说明 |
|---|
| 产品名 / slug / 仓库名 | displayName、expo slug、repo 目录名 |
| bundle id / package | 如 com.xxx.app（dev/preview 环境自动加 .dev/.preview 后缀） |
| URL scheme | 深链 scheme |
| 品牌主色 | 建议「单一品牌色 + 12 级灰阶」哲学；确认一个 hex |
| 深色模式策略 | 跟随系统 vs 固定浅色+手动切换（显式决策，见原则 9） |
| 可选模块（多选） | ① Supabase auth+云同步 ② 付费（IAP/Stripe + credits）③ i18n 多语 ④ 观测（Sentry+PostHog）⑤ EAS 构建/发布 ⑥ Maestro E2E |
Step 1 — 仓库与工具链骨架 → references/01-scaffold.md
pnpm monorepo（apps/mobile + packages/core）、Expo app 创建与改造（app.config.ts / metro / babel / tsconfig / eslint / jest）、husky+commitlint、CI quality-gate、AGENTS.md 规范。
Step 2 — 应用架构 → references/02-app-architecture.md
Expo Router 路由骨架、root layout 与 provider 栈、design tokens 单源 + Themed 组件族、screen 工厂与布局原语、icon 注册表、字体策略、feature 模块内形。
Step 3 — 状态与数据层 → references/03-state-data.md
zustand 薄店（无 persist）、MMKV 分层存储、SQLite 单连接管理器 + repository + 手写 migrations、per-user 文件存储、错误双通道、全套测试模式。
Step 4 — 可选模块
- Supabase auth / sync / payments →
references/04-backend-supabase.md
- i18n / Sentry / PostHog / 版本更新检查 / Maestro / 发布 →
references/05-cross-cutting.md
全程对照 references/06-hard-lessons.md——生产事故与深坑清单（WebView opacity、OS 备份撕裂同步游标、大文件 OOM、content:// URI、真库回放 migration 等），涉及对应场景时先读再写。
Step 5 — 验证与首提交
pnpm install → pnpm mobile:lint && pnpm mobile:typecheck && pnpm mobile:test 全绿（lint 从 --max-warnings 0 起步，不给未来留 warning 债）。pnpm --filter <core-package> test 绿。- 不启动 dev server / 模拟器（除非用户明确要求）。
git init + 初始 commit（chore: scaffold <app> from create-app template）。
分层清单
核心必装（每个新 app 都要）：monorepo 骨架、Expo Router + typedRoutes、design tokens 单源 + Themed 组件、zustand+MMKV、lint/typecheck/jest 全链、husky+CI、AGENTS.md 规范、错误双通道骨架（观测 wrapper 可先 no-op）。
按需可选：SQLite（有结构化本地数据才装）、Supabase auth+sync、payments、i18n、观测、EAS、Maestro。宁可后补也不预装空壳——空模块 = 噪音。
工程纪律（写进新 repo 的 AGENTS.md，机制而非口号）
- bug 先写失败测试再修——测试转绿即验收信号；偶现 bug 必须先做出确定性复现，禁止「看起来修好了」。
- PR 验收清单：自动测试覆盖了什么 + 剩余手动 QA 项（含真机项），写进 PR body。
- pitfalls.md 活文档制度：每次踩坑（≥半天排查或真实事故）立刻记一条「现象→根因→规则」；新 repo 第一天就建这个文件——本 skill 的
references/06 就是它的种子。
- 定时任务/批处理上线后 24h 查一次日志，确认无持续失败模式。
- lint warning 零容忍从第一天开始（
--max-warnings 0），债务只会单向增长。
不可违背的架构原则（生产教训提炼）
- 路由文件是瘦包装，UI/逻辑全在
src/features/<name>/。
- 品牌色单源在
packages/core/src/design/colors.ts；tailwind config 不硬编码品牌色（生产教训：config 残留模板默认蓝与陈旧色值，和 token 真相漂移数月无人察觉）。
- zustand 不用 persist middleware：store = 内存投影；真持久化在 MMKV/SQLite 服务层，action 内 write-through。
- 依赖单向：UI → stores → services → packages → SDK。services 不 import React/zustand/stores。
- SQLite 单连接 + 写串行（promise 链 + exclusive transaction + busy retry），per-user db 文件。
- 网络同步引擎惰性构造（getter 内 new），module load 期禁止实例化——否则破坏测试 partial-mock，且在用户登录前就创建了网络/存储对象。
- 观测唯一入口 wrapper +
setUser({id}) only（PII 铁律）+ 封闭 ErrorCategory；分析事件用 snake_case typed event map。
- Auth gate = 纯决策函数 + 瘦 effect 组件（永远
router.replace）；splash 等 fonts+storage+auth 全 ready 才 hide。
- 决策点显式过，不盲抄：OTA（expo-updates vs 自建版本检查+强更能力）、跟随系统深色与否、特殊显示模式（如 eink）支持与否。
- AGENTS.md canonical + CLAUDE.md symlink + verify 脚本进 CI，从第一天开始。
