SuperAPI AI 工具集

app-startup-and-bootstrap

编程与开发

查看项目

更新于 10-18 18:03

技能介绍

用途

该技能用于为 Expo 应用定义并强制一条固定的冷启动顺序,覆盖从入口模块、根布局、应用根、启动屏保持与释放、存储打开、providers 挂载到后台刷新与可选套件接入的完整启动链路。它面向需要保证首帧真实、避免空白帧、避免启动屏永久停留或方向重启导致重复初始化的 React Native / Expo 项目。

主要能力

  • 规定入口导入顺序:polyfills 最先,expo-router/entry 最后,其后不得再有导入。
  • 规定根布局的副作用导入顺序:先安装错误网,再保持启动屏,带绑定的导入排在其后。
  • 规定启动屏在模块作用域保持一次,在应用根的方向门之下、启动门就绪时通过 useStartupReady 释放一次。
  • 规定数据层在应用根的启动初始化器中同步打开一次,随后依次连接错误日志 sink、水合 query client、settings 与 stores,再创建可选套件。
  • 规定启动路径不 await、不使用 promise 链;首屏真正需要的异步工作作为 createStartupGate 的非交互阻塞任务,deadlineMs 为字面量且不超过 3000。
  • 规定字体通过 expo-font 配置插件嵌入,不在运行时加载。
  • 规定 providers 按依赖顺序嵌套且每个只挂载一次,并给出顺序:services、data、query、settings store、stores、preferences、root stack(gesture root、keyboard、RootMotion、navigation theme、session、feedback、ads、games、AppStack)。
  • 规定延迟工作从拥有它的组件或服务在启动屏释放后开始,不使用 InteractionManager。
  • 规定缓冲写入由一个根 hook useFlushOnBackground 在应用根中调用一次,且位于 useCheckpointOnBackground 之前。
  • 规定可选套件通过 createRootKits 注册表接入,根文件不导入套件;Metro 套件列在 scripts/metro/metro-kits.ts。
  • 提供零依赖检查器 scripts/check-startup.mjs,从仓库根运行并输出 RESULT: PASS。

使用方式

  1. 阅读 references/startup-order.md,其第 1 节列出每一步、所属文件与负责技能,先确定改动应放在哪里。
  2. 新应用或尚无根骨架时,复制模板:templates/src/app/_layout.tsx、templates/src/features/root-navigator/ 下的 app-root.tsx、root-stack.tsx、app-stack.tsx、hold-splash.ts、startup-gate.ts、use-startup-ready.ts、background-flush.ts、use-flush-on-background.ts、root-kits.tsx 及各自测试,templates/src/services/root-kits/root-kit.ts 及测试,templates/src/services/create-root-kits.ts,以及 templates/contracts/startup.json。这些模板依赖组合根、错误网、DirectionGate、数据层、watchSystemA11y 与 MotionConfig、useScreenAnimation 和导航主题,缺失时先用对应技能搭建。
  3. 添加启动环节:可选套件在 createRootKits 中加一条注册;应用部件在 startApp 的顺序表对应行创建、在树中对应位置挂 provider,若是新部件则加入 contracts/startup.json 的 appRootOrder。
  4. 异步工作按 references/startup-gate-and-deferred-work.md 第 1 节判断是否阻塞首屏;默认延迟,阻塞任务返回 Result 并进入 createStartupGate({ blocking }),并配测试覆盖 resolve、fail、hang。
  5. 启动屏问题参考 references/splash-screen.md 第 3-4 节与陷阱表。
  6. 缓冲写入参考 references/lifecycle-flush.md,模仿 examples/task-draft-buffer.ts,从 startApp 返回其 flusher。
  7. 测试:npx jest src/features/root-navigator --ci --maxWorkers=2,然后 npm run typecheck 与 npx eslint . --max-warnings 0。
  8. 运行检查器:node ${CLAUDE_SKILL_DIR}/scripts/check-startup.mjs .,按 references/checker-rules.md 查 FAIL 规则,修复至 RESULT: PASS。
  9. 在设备上手动验证:每个发布候选、每个语言布局方向,在指定模拟器与模拟器上冷启动 release 构建,确认启动屏后一帧即首屏,输入草稿后划掉应用再启动草稿仍在。

适用场景

适用于使用 Expo Router 的 React Native 应用,尤其是需要严格控制冷启动顺序、启动屏行为、方向重启、存储打开时机、providers 顺序、后台刷新与可选套件接入的项目。也适用于需要以检查器自动验证启动骨架一致性的团队。

限制

资料未提供该技能的收费、价格、平台支持范围或效果保证。启动屏行为验证需在 release 构建上进行,Expo Go 会显示应用图标而非启动屏,开发构建不会应用全部启动屏配置属性。检查器预期无 SKIP 行,因为其读取的每个文件都属于本技能。