CLI v1.0.0

🎉 全新的 CLI —— create-heroui-native-app —— 现已成为启动 HeroUI Native 项目最快捷的方式。一条命令即可生成一个完整的 Expo Router 应用，内置 HeroUI Native、Uniwind、Tailwind CSS、所有必需的 peer 依赖以及 Provider 包装，无需再手动配置 global.css、metro.config.js 或 app/_layout.tsx。

快速开始

npx create-heroui-native-app@latest my-app

pnpm create heroui-native-app@latest my-app

yarn create heroui-native-app my-app

bun create heroui-native-app@latest my-app

随后启动开发服务器：

cd my-app
npm run start

到此为止。如需完整流程，请直接阅读快速开始指南。

起始模板

CLI 自带两套模板。可在交互式选择器中选择，或通过命令行参数跳过提示：

npx create-heroui-native-app@latest my-app --expo
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm

你将得到什么

每个生成的项目都已预先配置：

• Expo SDK 56 + Expo Router，并启用类型化路由
• React 19.2 + React Native 0.85.2 + Hermes v1（SDK 56 默认启用）
• HeroUI Native：在 app/_layout.tsx 中由 HeroUINativeProvider 与 GestureHandlerRootView 包裹
• Uniwind + Tailwind CSS：通过 metro.config.js 与 global.css 完成接入
• 所有 HeroUI Native 必需的 peer 依赖已锁定到兼容版本：react-native-reanimated、react-native-gesture-handler、react-native-worklets、react-native-safe-area-context、react-native-svg、tailwind-variants、tailwind-merge
• 内置 react-native-screens，让 HeroUI 的遮罩组件（Dialog、Menu、Popover、Select、BottomSheet、Toast）开箱即用
• @expo/metro-runtime（SDK 56 上 Expo Router 需要的 peer 依赖）
• 仅使用 babel-preset-expo 的 babel.config.js（worklets 已由该 preset 处理）
• 启用 strict: true 与 @/* 路径别名的 TypeScript 配置

CLI 参考

create-heroui-native-app [project-name] [options]

示例

# 完全交互式 —— 同时提示项目名与模板
npx create-heroui-native-app@latest

# 已指定项目名，仍展示模板选择器
npx create-heroui-native-app@latest my-app

# 完全非交互式
npx create-heroui-native-app@latest my-app --expo

# 使用 Tabs 模板，并通过 pnpm 安装依赖
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm

# 仅生成项目，不安装依赖、不初始化 git
npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git

系统要求

• Node.js 20.19.4+（Expo SDK 56 / React Native 0.85 的要求）
• 构建原生 iOS 时需要 iOS 16.4+（Expo SDK 56 的部署目标）
• macOS、Linux 或 Windows

链接

• 快速开始指南
• HeroUI Native MCP 服务器