novaui-cli

The CLI for NovaUI — a React Native UI component library with 50+ components built on NativeWind (Tailwind CSS for React Native).

Inspired by shadcn/ui, adapted for mobile. Components are copied directly into your project — you own the code, customize anything.

Prerequisites

Before using NovaUI CLI, ensure you have:

• React >= 18
• React Native >= 0.72
• NativeWind >= 4 (must be set up first — see NativeWind docs)
• Tailwind CSS >= 3

⚠️ Important: NovaUI requires NativeWind to be properly configured. If you haven't set up NativeWind yet, please follow the NativeWind installation guide before proceeding.

Quick Start

Step 1: Set Up NativeWind

NovaUI requires NativeWind to be installed and configured. If you haven't done this yet:

1. Install NativeWind and Tailwind CSS:

   npm install nativewind
   npm install -D tailwindcss

2. Initialize Tailwind:

   npx tailwindcss init

3. Configure NativeWind in your tailwind.config.js:

   module.exports = {
     content: ["./App.{js,jsx,ts,tsx}", "./src/**/*.{js,jsx,ts,tsx}"],
     presets: [require("nativewind/preset")],
   }

4. Add NativeWind to your Babel config (babel.config.js):

   module.exports = {
     plugins: ["nativewind/babel"],
   }

For complete setup instructions, visit the NativeWind documentation.

Step 2: Initialize NovaUI

Run the interactive setup command:

npx novaui-cli init

The CLI will prompt you to configure file paths:

? Path for global.css? (src/global.css)
? Path for UI components? (src/components/ui)
? Path for lib (utils)? (src/lib)

Press Enter to accept defaults or type custom paths.

What Gets Created

The init command creates:

• components.json — Stores your configured paths for future component additions
• tailwind.config.js — NovaUI theme configuration with colors, border radius, and NativeWind preset
• global.css — Light and dark theme CSS variables
• lib/utils.ts — The cn() utility function for merging Tailwind classes

Dependencies Installed

The CLI automatically installs:

• nativewind — Tailwind CSS for React Native
• tailwindcss — Tailwind CSS framework
• clsx — Utility for constructing className strings
• tailwind-merge — Utility to merge Tailwind CSS classes without conflicts
• class-variance-authority — Utility for creating type-safe component variants

Step 3: Import Global Styles

Import the global.css file in your root entry file (typically App.tsx):

import "./src/global.css"

export default function App() {
  // Your app content
}

This ensures NovaUI's theme variables are available throughout your app.

Step 4: Add Components

Add components to your project:

npx novaui-cli add button
npx novaui-cli add card
npx novaui-cli add dialog

Components are copied into your configured directory (default: src/components/ui/). Each component's dependencies are installed automatically.

Component naming: Use the filename without extension — button, card, alert-dialog, dropdown-menu, etc.

Step 5: Use Components

Import and use components in your app:

import { Button } from "./src/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "./src/components/ui/card"

export default function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome to NovaUI</CardTitle>
      </CardHeader>
      <CardContent>
        <Button onPress={() => console.log("Pressed!")}>
          Get Started
        </Button>
      </CardContent>
    </Card>
  )
}

CLI Commands

| Command | Description | |---------|-------------| | npx novaui-cli init | Interactive setup — creates config, Tailwind config, global CSS, and utils | | npx novaui-cli add <name> | Add a component to your project | | npx novaui-cli --version | Show CLI version | | npx novaui-cli --help | Show help and available commands |

Available Components

NovaUI includes 50+ components ready to use:

Layout & Structure: Accordion, Alert, Alert Dialog, Aspect Ratio, Card, Collapsible, Dialog, Drawer, Separator, Sheet

Navigation: Breadcrumb, Command, Context Menu, Dropdown Menu, Menubar, Navigation Menu, Tabs

Forms & Input: Button, Button Group, Checkbox, Combobox, Field, Input, Input Group, Input OTP, Label, Radio Group, Select, Switch, Textarea, Toggle, Toggle Group

Data Display: Avatar, Badge, Calendar, Carousel, Chart, Empty, Pagination, Progress, Skeleton, Spinner, Table, Typography

Overlays: Hover Card, Popover, Resizable, Scroll Area

Text: Text

Add any component with:

npx novaui-cli add <component-name>

Component naming: Use the filename without extension — button, card, alert-dialog, dropdown-menu, etc.

Configuration

Customizing Paths

Running init creates a components.json file in your project root:

{
  "globalCss": "src/global.css",
  "componentsUi": "src/components/ui",
  "lib": "src/lib"
}

To change these paths:

• Edit components.json directly, or
• Run npx novaui-cli init again to reconfigure

Customizing Themes

NovaUI components use CSS variables for theming. Customize colors, spacing, and design tokens in your global.css file. The generated tailwind.config.js includes a comprehensive theme configuration you can customize.

Troubleshooting

Components Not Styling Correctly

• ✅ Ensure global.css is imported in your root file
• ✅ Verify NativeWind is configured in babel.config.js
• ✅ Check that tailwind.config.js includes the NativeWind preset
• ✅ Ensure content paths in tailwind.config.js include your component directories

Build Issues

• Clear cache: npx react-native start --reset-cache
• Reinstall dependencies: rm -rf node_modules && npm install
• Verify all peer dependencies are installed

Requirements

| Package | Minimum Version | |---------|----------------| | react | >= 18 | | react-native | >= 0.72 | | nativewind | >= 4 | | tailwindcss | >= 3 |

Resources

• 📖 NovaUI Documentation — Full component documentation
• 🎨 NativeWind Documentation — Learn more about NativeWind
• 🐛 GitHub Issues — Report bugs or request features
• 💬 GitHub Discussions — Ask questions

License

MIT