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

comet format

comet test

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

技术选型（默认）

临时初始化（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

定期运行

npx expo doctor

pnpm outdated