cli

rootnative

CLI for adding RootNative UI components directly into your React Native or Expo project. Inspired by shadcn/ui — you own the code.

Quick start

Start a new project:

npx rootnative create my-app

Or add components to an existing project:

npx rootnative init
npx rootnative add button card

How it works

Instead of installing components as an npm package, the CLI copies the source files into your project. You get full ownership — customize styles, adjust behavior, or remove what you don't need.

The theme system (@rootnative/core) stays as an npm dependency so theme updates propagate automatically.

Requirements

• Node.js >= 18
• Expo SDK 58: React Native >=0.88.0 <0.89.0 and React >=19.3.0 <20.0.0, the band the published packages declare
• TypeScript project (recommended)

Commands

rootnative create [name]

Scaffold a new Expo project with RootNative UI pre-configured (ThemeProvider wired up, example components included).

npx rootnative create my-app

It prompts for project name, display name, template, and package manager.

Options:

Flag	Description
-y, --yes	Skip prompts and use defaults
-t, --template <name>	Template to use (blank, with-router)
--package-manager <pm>	Package manager to use (npm, yarn, pnpm, bun)

Non-interactive mode for CI/automation:

npx rootnative create my-app -y --template with-router --package-manager pnpm

rootnative init

Initialize your project for RootNative UI.

npx rootnative init

This will:

1. Detect your project type (Expo or bare React Native)
2. Detect your package manager (npm, yarn, pnpm, bun)
3. Detect path aliases from your tsconfig.json
4. Prompt for component and utility output directories
5. Create an rootnative.json config file
6. Offer to add the LLM-docs pointer to your project's CLAUDE.md
7. Offer to install @rootnative/core

Steps 6 and 7 are confirmation prompts; -y accepts both.

Options:

Flag	Description
-y, --yes	Skip all prompts and use detected defaults
--components-alias <alias>	Components install path (default: @/components/ui)
--lib-alias <alias>	Utility files path (default: @/lib)
--package-manager <pm>	Package manager to use (npm, yarn, pnpm, bun)

Non-interactive mode for CI/automation:

# Accept all defaults
npx rootnative init -y

# With custom paths
npx rootnative init -y --components-alias "~/ui" --lib-alias "~/utils"

rootnative add <components...>

Add one or more components to your project.

npx rootnative add button
npx rootnative add card chip text-field
npx rootnative add appbar  # auto-adds button + icon-button + typography dependencies

Options:

Flag	Description
-f, --force	Overwrite existing components
-d, --dry-run	Preview what would be installed without writing files
--package-manager <pm>	Package manager to use (npm, yarn, pnpm, bun)

The add command:

1. Resolves the full dependency graph (e.g. appbar requires button, icon-button and typography)
2. Shows a plan of components, utilities, and npm packages to install
3. Copies component files with import paths rewritten to match your project
4. Generates a utility barrel file (rootnative-utils.ts)
5. Installs required npm dependencies

rootnative update [components...]

Update installed components to the latest version from the registry.

npx rootnative update button        # update specific components
npx rootnative update --all         # update everything installed
npx rootnative update --all --dry-run  # preview the diff first

Options:

Flag	Description
-a, --all	Update all installed components
-d, --dry-run	Show diff without applying changes

Local modifications are detected by diffing against the registry source — review the diff with --dry-run before applying if you've customized component files.

rootnative upgrade

Upgrade @rootnative/core to the latest published version and install any new peer dependencies.

npx rootnative upgrade

Options:

Flag	Description
-y, --yes	Skip confirmation prompt
-a, --all	Also update all installed component files
--package-manager <pm>	Package manager to use (npm, yarn, pnpm, bun)

The upgrade command:

1. Detects the installed @rootnative/core version from node_modules
2. Fetches the latest version from the npm registry
3. Compares peer dependencies between the installed and latest versions
4. Shows a plan with the version bump, new required peer deps, changed ranges, and removed deps
5. Upgrades @rootnative/core and installs any new required peer dependencies
6. Reports optional peer deps that aren't installed (does not auto-install them)
7. Lists peer deps that are no longer required so you can remove them manually
8. Moves registryVersion in rootnative.json forward to the new release tag, so subsequent add/update calls fetch matching sources
9. With -a, --all, also updates the installed component files

Non-interactive mode for CI/automation:

npx rootnative upgrade -y

rootnative list

Show all available components with their install status.

npx rootnative list

rootnative doctor

Check your project for common issues.

npx rootnative doctor

Checks include:

• rootnative.json exists and is valid
• @rootnative/core is installed
• React Native version compatibility
• Installed component file integrity
• @rootnative/inertia — a hard failure when missing, since every animated component needs it
• Optional peer dependencies (react-native-safe-area-context, and @react-native-vector-icons/material-design-icons for mdiResolver) — reported as warnings

Configuration

rootnative init creates an rootnative.json in your project root:

{
  "$schema": "https://rootnative.github.io/ui/schema.json",
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib"
  },
  "registryUrl": "https://raw.githubusercontent.com/rootnative/ui",
  "registryVersion": "v0.0.0-alpha.4"
}

Field	Description
aliases.components	Where component directories are created
aliases.lib	Where utility files are placed
registryUrl	Base URL for fetching component source files
registryVersion	Git ref to fetch from (branch, tag, or commit). init pins this to the v<version> tag of the latest published release, falling back to main only when npm is unreachable or the tag isn't pushed yet. upgrade moves the pin forward

Output structure

After running npx rootnative add button appbar:

src/
  components/
    ui/
      button/
        Button.tsx
        types.ts
        styles.ts
        index.ts
        elevationShadow.ts  # shared internal, flattened per component
        usePressMorph.ts
        useStateLayer.ts
      icon-button/          # auto-added (appbar dependency)
        IconButton.tsx
        types.ts
        styles.ts
        index.ts
        useBooleanProgress.ts
        usePressMorph.ts
        useStateLayer.ts
      typography/           # auto-added (appbar dependency)
        Typography.tsx
        types.ts
        styles.ts
        index.ts
      appbar/
        AppBar.tsx
        types.ts
        styles.ts
        index.ts
        safe-area.tsx
  lib/
    color.ts
    elevation.ts
    pressable.ts
    render-icon.tsx
    rtl.ts
    rootnative-utils.ts    # generated barrel

Shared internal hooks (useStateLayer, usePressMorph, …) are copied into each component directory that uses them rather than into a shared folder, so each installed component stays self-contained.

Available components

Component	Description
typography	Text component with 15 MD3 type scale variants
button	5 variants (filled, elevated, outlined, text, tonal) with icon support
button-group	Standard and connected button groups with single or multi-select toggle behavior
icon-button	4 variants (filled, tonal, outlined, standard) with toggle support
fab	Floating action button with 4 color variants, 3 sizes, and optional extended label
appbar	Top app bar with 4 variants and SafeAreaView support
avatar	Circular avatar with image, icon, or text initials and 5 sizes
card	3 variants (elevated, filled, outlined) with optional press handler
chip	4 variants (assist, filter, input, suggestion) with icon/avatar support
checkbox	Binary selection control
radio	Single-choice selection control
switch	Toggle control with optional icons
slider	Single-thumb or range slider with continuous and discrete modes
progress	Linear and circular progress indicators (determinate and indeterminate)
text-field	Text input with animated floating label, 2 variants (filled, outlined)
layout	Layout primitives: Box, Row, Column, Grid with responsive columns and spanning cells, and SafeAreaView wrapper
list	List container with interactive items and dividers
divider	Horizontal or vertical 1dp rule with optional leading/trailing insets and thickness/color overrides.
loading-indicator	MD3 Expressive shape-morphing loading spinner (contained + uncontained, determinate + indeterminate)
portal	Render children into a host elsewhere in the tree (overlays, dialogs, sheets)
dialog	Basic and full-screen modal dialogs with Icon / Title / Content / Actions slots, scrim, and Android back handling.
snackbar	Imperative snackbar queue — SnackbarProvider plus useSnackbar() with actions, durations, and safe-area aware placement.
menu	Anchored dropdown menu (Menu + Menu.Item) that flips and shifts to stay on screen, with self-managing or controlled visibility.
tooltip	Plain and rich tooltips anchored to a control, shown on hover or a long press
bottom-sheet	MD3 bottom sheet — modal (scrim) and standard variants, drag handle, velocity-based snap points, drag-to-dismiss.
tabs	Primary and secondary tab rows, fixed or scrollable, with a sliding active indicator
navigation-bar	MD3 navigation bar — 80dp bottom destination bar with an animated indicator pill
keyboard-avoiding-wrapper	Zero-config keyboard-aware wrapper for form layouts

Import rewriting

The CLI rewrites imports so copied files work in your project:

Original (library source)	Rewritten to
@rootnative/core	Unchanged (npm package)
@rootnative/utils	@/lib/rootnative-utils (local barrel)
../icon-button	@/components/ui/icon-button (alias path)
./styles	Unchanged (same directory)

Usage after adding components

import { ThemeProvider } from '@rootnative/core'
import { Button } from '@/components/ui/button'
import { Card } from '@/components/ui/card'

export default function App() {
  return (
    <ThemeProvider>
      <Card>
        <Button variant="filled" onPress={() => {}}>
          Press me
        </Button>
      </Card>
    </ThemeProvider>
  )
}

Docs

Full docs: https://rootnative.github.io/ui/cli

LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt — or read node_modules/@rootnative/cli/llms.txt for the exact installed version.

License

MIT