CLI

@moe-ui/cli@0.1.0-beta.1 is a Node.js 20+ executable. Use the npm beta tag while the release is in prerelease.

beta.1Node.js 20+

Start with one command.

Detect the framework, choose a styling engine, and create the complete Moe UI foundation without leaving your terminal.

• Next.js
• Expo
• Uniwind
• NativeWind

Terminal

Package manager

pnpmnpmyarnbun

$pnpm dlx @moe-ui/cli@beta init

✓ Project detected✓ Theme configured✓ Ready to add components

init

$moe-ui init [options]

Initializes an existing TypeScript Next.js App Router or Expo project. The framework, package manager, src/ layout, and supported entry point are detected automatically.

--stylinguniwind | nativewind

Bypass the interactive styling-engine selection.

--yes

Accept the non-destructive Uniwind default.

--cwd<path>

Target a different application package.

--package-managerpnpm | npm | yarn | bun

Override lockfile detection.

--no-install

Write configuration without installing dependencies.

In a non-interactive environment, pass --styling or --yes. If both Next.js and Expo appear in the same package, target the intended application with --cwd.

Initialization preflights every required transformation. If an existing Next, Metro, PostCSS, root entry, CSS entry, or Moe UI configuration cannot be transformed safely, the command exits before writing project files.

The framework and styling engine are persisted in schema v2 of components.json. Schema v1 is read as Next.js + Uniwind and upgraded on the next initialization. Passing a different --styling value to an initialized project is rejected because automatic engine migration could discard local configuration.

add

$moe-ui add <components...> [options]

Fetches registry metadata, validates integrity, resolves dependencies recursively, and writes owned component source into the configured paths.

--cwd<path>

Target a different initialized application.

--overwrite

Replace conflicting component source deliberately.

--no-install

Write source without installing package dependencies.

The stored framework controls dependency installation: Expo-native packages use expo install, while ordinary dependencies use the detected package manager.

Without --overwrite, a file with different local content is protected and the command exits with the exact conflict. Re-running against unchanged installed source performs no write.

Examples

Troubleshooting

Unsupported project

The beta requires TypeScript and either a Next.js App Router layout or an Expo application entry. Next.js Pages Router and JavaScript-only projects are rejected intentionally.

Ambiguous framework

If one package declares both next and expo, run the command with --cwd pointing at the individual Next.js or Expo app. The initializer does not guess which bundler configuration to edit.

Config cannot be transformed

The CLI only composes configurations it can recognize without discarding behavior. Follow the printed manual instructions or simplify the relevant export, then rerun init.

NativeWind preview requirements

NativeWind initialization uses the v5 preview with Tailwind CSS 4 and react-native-css. Full native support requires React Native 0.81 or newer, the New Architecture, and Reanimated 4. NativeWind 5 no longer uses a Tailwind configuration file, Babel preset, or jsxImportSource; remove those v4 integrations before rerunning init in an existing project.

Styling engine is locked

Moe UI will not rewrite a configured Uniwind project into NativeWind, or the reverse. Preserve your source, migrate the bundler and theme configuration using the styling engine's guide, then update components.json deliberately.

Registry or network failure

No component files are committed until every requested item and recursive dependency has been fetched and validated. Retry after connectivity returns or set the registry URL in components.json to an approved mirror.

Local changes conflict

Compare your file with the content field at /r/<component>.json. Keep your local version, merge manually, or rerun with --overwrite after saving the changes you need.