Comet 脚手架命令规范

基于 React Native 通用脚手架设计方案的 CLI 命令与配置约定。

核心配置文件

comet.yaml

脚手架的单一配置源，记录所有工程约定：

name: my_app
org: com.example

package_manager: pnpm

build_tool: expo_prebuild # expo_prebuild | bare
architecture: new # new | old
integration: greenfield # greenfield | brownfield

state_management: zustand
server_state: tanstack_query
router: react_navigation

styling_engine: nativewind # nativewind | unistyles | restyle | stylesheet
forms: rhf_zod # rhf_zod | none
permissions: unified # unified | none
deep_linking: true
app_scheme: myapp
universal_links:
  - example.com

envs:
  - name: development
    android_flavor: dev
    ios_scheme: MyApp-Dev
    env_file: .env.development
  - name: staging
    android_flavor: stg
    ios_scheme: MyApp-Stg
    env_file: .env.staging
  - name: production
    android_flavor: prod
    ios_scheme: MyApp
    env_file: .env.production

modules:
  network: true
  storage: true
  i18n: true
  sentry: true
  svg: true
  e2e: false

---

CLI 命令

创建应用

comet create app <app_name> \
  --org com.example \
  --package-manager pnpm \
  --build-tool expo_prebuild \
  --architecture new \
  --integration greenfield \
  --state-management zustand \
  --router react_navigation \
  --enable-network \
  --enable-storage \
  --with-i18n \
  [--with-sentry] \
  [--with-ci]

行为：

• Expo Prebuild（默认）：基于 npx create-expo-app@latest 初始化
• Bare RN（可选）：基于 npx @react-native-community/cli init 初始化
• 生成标准目录结构（src/app、src/core、src/features）
• 初始化多环境配置
• 若指定 --with-ci，生成 .github/workflows/ci.yml

创建 Feature

comet create feature <feature_name> \
  [--route Counter] \
  [--no-domain] \
  [--no-data]

生成结构：

src/features/<feature_name>/
  presentation/
    screens/<FeatureName>Screen.tsx
    components/<FeatureName>View.tsx
    stores/use<FeatureName>Store.ts
  domain/
    entities/<featureName>.ts
    repositories/<featureName>Repository.ts
  data/
    datasources/<FeatureName>RemoteDataSource.ts
    repositories/<FeatureName>RepositoryImpl.ts

选项：

• --route：自动在 Root Navigator 注册路由
• --no-domain：不生成 domain 层
• --no-data：不生成 data 层

创建 Service

comet create service <service_name>

在 src/core/ 下生成服务骨架，如 analytics、crash_reporting 等。

辅助命令

命令	说明
comet lint	运行 ESLint + TypeScript 检查
comet format	运行 Prettier
comet test	运行 Jest（可选 Detox）
comet doctor	检查项目是否符合脚手架约定
comet upgrade-core	统一升级核心依赖版本

---

项目目录结构

顶层目录

project_root/
  app.json or app.config.ts   # Expo 配置
  android/                    # 原生 Android（Prebuild 生成）
  ios/                        # 原生 iOS（Prebuild 生成）
  src/                        # 源代码
  assets/                     # 静态资源
  __tests__/                  # 测试文件
  .vscode/ or .idea/          # IDE 配置
  babel.config.js
  metro.config.js
  tsconfig.json
  package.json
  comet.yaml                  # 脚手架配置
  README.md

src 目录结构

src/
  app/
    App.tsx                   # 根组件：Provider、NavigationContainer
    bootstrap.ts              # 应用引导初始化
    di.ts                     # 可选：跨 feature 核心依赖收口
    navigation/
      routes.ts               # 路由常量/类型（ParamList）
      RootNavigator.tsx       # Root Navigator

  core/                       # 无业务基础设施
    config/
      env.ts                  # 环境抽象
      appConfig.ts            # 配置汇总
    error/
      appError.ts             # 错误模型
      errorMapper.ts          # 错误映射
      errorReporter.ts        # 错误上报
    forms/
      formTypes.ts            # 表单类型
      zodSchemas.ts           # Zod Schema
    network/
      httpClient.ts           # axios/fetch 封装
      interceptors/
        authInterceptor.ts
        loggingInterceptor.ts
    permissions/
      permissions.ts          # 权限类型
      usePermission.ts        # 权限 Hook
    storage/
      keyValueStorage.ts      # KV 存储抽象
      secureStorage.ts        # 安全存储
    theme/
      tokens.ts               # 设计 token
      theme.ts                # 主题对象
    styling/
      styling.ts              # 样式引擎适配
    i18n/
      i18n.ts                 # i18next 初始化
    utils/
      logger.ts
      result.ts               # Result 类型
    components/
      AppScaffold.tsx
      LoadingIndicator.tsx
      ErrorView.tsx
      PrimaryButton.tsx

  features/                   # Feature-first 业务模块
    counter/                  # 示例 feature
      presentation/
        screens/
          CounterScreen.tsx
        components/
          CounterView.tsx
        stores/
          useCounterStore.ts
      domain/
        entities/
          counter.ts
        repositories/
          counterRepository.ts
      data/
        datasources/
          counterLocalDataSource.ts
        repositories/
          counterRepositoryImpl.ts

---

技术选型（默认）

类别	技术
构建工具	Expo（Prebuild / CNG）
底层架构	New Architecture
语言	TypeScript（strict）
包管理	pnpm
导航	React Navigation 7
状态管理	Zustand + TanStack Query
样式	NativeWind
表单	React Hook Form + Zod
网络	axios
存储	AsyncStorage / MMKV
国际化	i18next
监控	Sentry
测试	Jest + @testing-library/react-native

---

临时初始化（comet 未落地前）

Expo（推荐）

npx create-expo-app@latest MyApp
cd MyApp
npx expo start

# 需要原生工程时
npx expo prebuild --clean

Bare React Native

npx @react-native-community/cli@latest init MyApp
cd MyApp
npx react-native run-android
# 或
npx react-native run-ios

---

环境切换

原生构建维度

• iOS：Scheme/Configuration（Debug/Staging/Release）
• Android：productFlavors（dev/staging/prod）+ buildTypes

JS 侧读取

• Expo：app.config.ts + EAS 环境变量
• Bare RN：react-native-config + .env.*

运行脚本示例

{
  "scripts": {
    "ios:dev": "expo start --ios",
    "ios:stg": "expo start --ios --variant staging",
    "android:dev": "expo start --android",
    "android:stg": "expo start --android --variant staging"
  }
}

---

依赖版本参考（2025-12）

以模板 package.json + lockfile 为准，以下仅供参考：

包	版本
react	19.2.3
react-native	0.83.0
@react-navigation/native	7.1.25
zustand	5.0.9
@tanstack/react-query	5.90.12
axios	1.13.2
i18next	25.7.2
@sentry/react-native	7.7.0

定期运行 npx expo doctor 和 pnpm outdated 检查兼容性。