create-heroui-native-app

A CLI for scaffolding a new React Native (Expo) project preconfigured with HeroUI Native, Uniwind (Tailwind CSS for React Native), and Expo Router.

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

Templates

The CLI ships with two templates. Pass a shorthand flag to skip the interactive picker.

| Flag | Template | Description | | ------------- | ----------- | ---------------------------------------------------------------- | | --expo | expo | Single-screen Expo Router app with a HeroUI Button demo. | | --expo-tabs | expo-tabs | Expo Router tabs layout with two tabs (Button + Card demos). |

You can also use --template <id>:

npx create-heroui-native-app@latest my-app --template expo-tabs

Usage

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

| Option | Default | Description | | ----------------- | ------------- | ----------------------------------------------------------- | | [project-name] | (prompted) | Directory name to create. Must be a valid npm package name. | | --expo | | Use the single-screen Expo template. | | --expo-tabs | | Use the Expo + tabs template. | | --template <id> | | Use the template with the given id (expo or expo-tabs). | | --use-npm | auto-detected | Use npm to install dependencies. | | --use-yarn | auto-detected | Use yarn to install dependencies. | | --use-pnpm | auto-detected | Use pnpm to install dependencies. | | --use-bun | auto-detected | Use bun to install dependencies. | | --skip-install | false | Don't run the package manager install step. | | --skip-git | false | Don't initialize a git repository. | | -h, --help | | Print usage and exit. |

When no --template flag is provided, the CLI shows an interactive picker.

Examples

# Fully interactive — prompts for both project name and template
npx create-heroui-native-app@latest

# Project name supplied, template picker still shown
npx create-heroui-native-app@latest my-app

# Fully non-interactive
npx create-heroui-native-app@latest my-app --expo

# Tabs template, install with pnpm
npx create-heroui-native-app@latest my-app --expo-tabs --use-pnpm

# Scaffold only, no install, no git
npx create-heroui-native-app@latest my-app --expo --skip-install --skip-git

Requirements

• Node.js 20.19.4+ (required by Expo SDK 56 / React Native 0.85)
• iOS 16.4+ when building native iOS (Expo SDK 56 deployment target)
• macOS, Linux, or Windows

What you get

Every template ships preconfigured with:

• Expo SDK 56 + Expo Router (typed routes enabled)
• React 19.2 + React Native 0.85.2 + Hermes v1 (default in SDK 56)
• HeroUI Native (heroui-native) wrapped in HeroUINativeProvider and GestureHandlerRootView in app/_layout.tsx
• Uniwind + Tailwind CSS wired through metro.config.js and global.css
• All HeroUI Native mandatory peer dependencies pinned to compatible versions: 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 (so HeroUI components like Dialog, Menu, Popover, Select, BottomSheet, and Toast work out of the box)
• @expo/metro-runtime (peer required by Expo Router in SDK 56)
• A babel.config.js that uses just babel-preset-expo (worklets are handled by the preset)
• TypeScript with strict: true and @/* path alias

After scaffolding, get started with:

cd my-app
npm run ios       # or: npm run android, npm run start

Contributing

Source lives at github.com/heroui-inc/create-heroui-native-app. See the repo's docs/ folder for templates, CLI internals, and the release flow.

License

Apache-2.0