magic-native-ui

The CLI that adds Magic Native UI components to an Expo app. It copies source files into your project — there is no component library to install.

Requires Expo SDK 57+ (React Native 0.86+), React 19 and Tailwind CSS v4.

Usage

npx magic-native-ui@latest init
npx magic-native-ui@latest add button dialog card
npx magic-native-ui@latest icon add heart star

Commands

| Command | Description | | --- | --- | | init | Writes components.json, creates the Tailwind entry stylesheet with theme tokens, configures Metro for Uniwind, adds the @/* alias and uniwind-env.d.ts, and installs the base dependencies. | | add [components...] | Adds components and everything they depend on. With no arguments it prompts. | | list (ls) | Lists the components in the registry. | | view <component> | Shows a component's dependencies and files. | | diff [component] | Reports which installed components have drifted from the registry. | | icon add [icons...] | Vendors Hugeicons into lib/hugeicons/icons.ts. With no arguments it prompts for a search term. | | icon list [query] (ls, search) | Searches the 5,437 free Hugeicons by name or alias. |

Flags

init — -y/--yes, --css <path>, --base-color <color>, --registry <url>, --skip-install, -c/--cwd <dir>

add — -y/--yes, -o/--overwrite, -a/--all, -p/--path <dir>, --dry-run, --skip-install, --registry <url>, -c/--cwd <dir>

icon add — -y/--yes, -o/--overwrite, -p/--path <dir>, --dry-run, --skip-install, --registry <url>, -c/--cwd <dir>

icon list — -l/--limit <count>, --registry <url>, -c/--cwd <dir>

Icons

The free Hugeicons set is 6.18 MB, so nothing is installed. The first icon add copies a small renderer into lib/hugeicons/, and every run merges the icons you named into lib/hugeicons/icons.ts — sorted, deduplicated and keeping whatever is already there.

import { Icon, HeartIcon } from '@/lib/hugeicons'

<Icon icon={HeartIcon} size={20} className="text-primary" />

Icons are addressed by registry name (heart), by an upstream alias (plus for AddIcon) or by the export itself (HeartIcon). Exports keep their upstream Hugeicons names, so anything you find in their docs is the same symbol here. Since the CLI regenerates the barrel, it refuses to write to it if you have added code of your own — keep that in a separate file.

Browse the set at native-ui.magicwebs.ai/docs/icons.

components.json

{
  "style": "default",
  "tsx": true,
  "tailwind": { "css": "global.css", "baseColor": "neutral" },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "utils": "@/lib/utils",
    "hooks": "@/hooks"
  },
  "registry": "https://native-ui.magicwebs.ai/r",
  "metroConfig": "metro.config.js"
}

Aliases are resolved through your tsconfig.json paths, and registry sources are rewritten to match them on the way in.

MAGIC_NATIVE_UI_REGISTRY overrides the default registry URL, which is useful when developing against a local registry.

Development

bun install
bun run build          # tsup -> dist/index.js
bun run typecheck