June 4, 2026

🎉 A new CLI — create-heroui-native-app — is now the fastest way to start a HeroUI Native project. One command scaffolds a complete Expo Router app with HeroUI Native, Uniwind, Tailwind CSS, every required peer dependency, and the provider wiring already in place. No manual setup of global.css, metro.config.js, or app/_layout.tsx.

Quick Start

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

Then start the dev server:

cd my-app
npm run start

That's it. Skip ahead to the Quick Start guide for the full walkthrough.

Starter Templates

The CLI ships with two templates. Pick one in the interactive picker, or pass a flag to skip the prompt.

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).

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

What You Get

Every scaffolded project ships preconfigured with:

Expo SDK 56 + Expo Router with typed routes enabled
React 19.2 + React Native 0.85.2 + Hermes v1 (default in SDK 56)
HeroUI Native wrapped in HeroUINativeProvider and GestureHandlerRootView inside 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 overlay components (Dialog, Menu, Popover, Select, BottomSheet, Toast) work out of the box
@expo/metro-runtime (required peer for Expo Router on SDK 56)
A babel.config.js using just babel-preset-expo (worklets handled by the preset)
TypeScript with strict: true and the @/* path alias

CLI Reference

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

Option	Description
`[project-name]`	Directory name to create. Prompted if omitted. 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` / `--use-yarn` / `--use-pnpm` / `--use-bun`	Force a specific package manager (otherwise auto-detected).
`--skip-install`	Don't run the package manager install step.
`--skip-git`	Don't initialize a git repository.
`-h`, `--help`	Print usage and exit.

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

Already have an app? The CLI is for new projects. To add HeroUI Native to an existing React Native or Expo app, follow Option 2 in the Quick Start.

create-heroui-native-app