@v0xoss/oss-cli NPM

The CLI offers a comprehensive suite of commands to initialize, manage, and improve your HeroUI projects. It enables you to add, remove, or upgrade individual components, assess the health of your project, and more.

Quick Start

Note: The HeroUI CLI requires Node.js 18.17.x+ or later

You can choose the following ways to start the HeroUI CLI.

Npx

npx heroui-cli@latest

Global Installation

npm install -g heroui-cli

Usage

Usage: heroui [command]

Options:
  -v, --version                      Output the current version
  --no-cache                         Disable cache, by default data will be cached for 30m after the first request
  -d, --debug                        Debug mode will not install dependencies
  -h --help                          Display help information for commands

Commands:
  init [options] [projectName]       Initializes a new project
  add [options] [components...]      Adds components to your project
  upgrade [options] [components...]  Upgrades project components to the latest versions
  remove [options] [components...]   Removes components from the project
  list [options]                     Lists all components, showing status, descriptions, and versions
  env [options]                      Displays debugging information for the local environment
  doctor [options]                   Checks for issues in the project
  help [command]                     Display help for command

Commands

Init

Initialize a new HeroUI project with official templates.

heroui init [projectName] [options]

Init Options

-t --template [string] The template to use for the new project e.g. app, pages, vite
-p --package [string] The package manager to use for the new project (default: npm)

Example

# Initialize a new HeroUI project with the app template, named my-heroui-app
heroui init my-heroui-app -t app

output:

HeroUI CLI v0.2.1

┌  Create a new project
│
◇  Select a template (Enter to select)
│  ● App (A Next.js 14 with app directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Pages (A Next.js 14 with pages directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with HeroUI (v2) and Tailwind CSS.)
│
◇  New project name (Enter to skip with default name)
│  my-heroui-app
│
◇  Select a package manager (Enter to select)
│  ● npm
│  ○ yarn
│  ○ pnpm
│  ○ bun
│
◇  Template created successfully!
│
◇  Next steps ───────╮
│                    │
│  cd my-heroui-app  │
│  npm install       │
│                    │
├────────────────────╯
│
└  🚀 Get started with npm run dev

Add

Add HeorUI components to your project.

Features

Auto add the missing required dependencies to your project
Auto add the required tailwindcss.config.js configuration to your project
Detect whether using pnpm, if so, add the required configuration to your .npmrc file

heroui add [components...] [options]

Add Options

-a --all boolean Add all the HeroUI components (default: false)
-p --packagePath string The path to the package.json file
-tw --tailwindPath string The path to the tailwind.config file file
-app --appPath string The path to the App.tsx file
--prettier boolean Add prettier format in the add content which required installed prettier - (default: false)
--addApp boolean Add App.tsx file content which required provider (default: false)
-b --beta boolean Add beta components (default: false)

Example

Without setting a specific component, the add command will show a list of available components.

heroui add

Output:

HeroUI CLI v0.2.1

? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◉  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◯  button
◯  card
◯  checkbox
◯  chip
◯  code

If you want to add a specific component, you can specify the component name.

heroui add button

Output:

HeroUI CLI v0.2.1

Adding the required dependencies: @heroui/button

pnpm add @heroui/button
Packages: +1
+
Progress: resolved 470, reused 462, downloaded 0, added 0, done

dependencies:
+ @heroui/button 2.0.24

Done in 3.4s

Tailwind CSS settings have been updated in: /project-path/tailwind.config.js

✅ Components added successfully

Upgrade

Upgrade the HeroUI components to the latest version.

heroui upgrade [components...] [options]

Upgrade Options

-p --packagePath string The path to the package.json file
-a --all boolean Upgrade all the HeroUI components (default: false)
-w --write boolean Write the upgrade version to package.json file (default: false)
-b --beta boolean Upgrade beta components (default: false)
-h --help Display help for command

Example

Upgrade the Button component to the latest version.

heroui upgrade button

Output:

HeroUI CLI v0.2.1

╭───────────────────────── Component ─────────────────────────╮
│  @heroui/button              ^2.0.11  ->  ^2.0.31       │
╰─────────────────────────────────────────────────────────────╯

Required min version: @heroui/theme>=2.1.0, tailwindcss>=3.4.0, react>=18.3.1, react-dom>=18.3.1
╭───────────────────── PeerDependencies ─────────────────────╮
│  @heroui/theme               2.0.1    ->  2.1.0        │
│  tailwindcss                     ^3.2.3   ->  ^3.4.0       │
│  react                           Missing  ->  18.3.1       │
│  react-dom                       Missing  ->  18.3.1       │
╰────────────────────────────────────────────────────────────╯
2 major, 2 minor, 1 patch

? Would you like to proceed with the upgrade? › - Use arrow-keys. Return to submit.
❯   Yes
    No

pnpm add @heroui/button@2.0.31 @heroui/theme@2.1.0 tailwindcss@3.4.0 react@18.3.1 react-dom@18.3.1

dependencies:
- @heroui/theme 2.0.1
+ @heroui/theme 2.1.0 (2.2.3 is available)
+ react 18.3.1
+ react-dom 18.3.1

Done in 1.8s

✅ Upgrade complete. All components are up to date.

Remove

Remove HeroUI components from your project.

Note: If there are no HeroUI components after removing, the required content will also be removed

heroui remove [components...] [options]

Remove Options

-p --packagePath string The path to the package.json file
-a --all boolean Remove all the HeroUI components (default: false)
-tw --tailwindPath string The path to the tailwind.config file file
--prettier boolean Add prettier format in the add content which required installed prettier - (default: false)

Example

Remove the Button component from your project.

heroui remove button

Output:

HeroUI CLI v0.2.1

❗️ Components slated for removal:
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package              │   Version              │   Status   │   Docs                                        │
│──────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/button   │   2.0.27 🚀latest      │   stable   │   https://heroui.com/docs/components/button   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
? Confirm removal of these components: › - Use arrow-keys. Return to submit.
❯   Yes
    No

pnpm remove  @heroui/button
Already up to date
Progress: resolved 474, reused 465, downloaded 0, added 0, done

dependencies:
- @heroui/button 2.0.27

Done in 2.1s

Remove the removed components tailwind content in file:/project-path/tailwind.config.js

✅ Successfully removed the specified HeroUI components: @heroui/button

List

List all the current installed components.

heroui list [options]

List Options

-p --packagePath string The path to the package.json file
-r --remote List all components available remotely

Example

heroui list

Output:

HeroUI CLI v0.2.1

Current installed components:

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package                    │   Version              │   Status    │   Docs                                              │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/autocomplete   │   2.0.10 🚀latest      │   stable    │   https://heroui.com/docs/components/autocomplete   │
│   @heroui/badge          │   2.0.24 🚀latest      │   stable    │   https://heroui.com/docs/components/badge          │
│   @heroui/button         │   2.0.27 🚀latest      │   stable    │   https://heroui.com/docs/components/button         │
│   @heroui/chip           │   2.0.25 🚀latest      │   stable    │   https://heroui.com/docs/components/chip           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Doctor

Check whether exist problem in your project by using the doctor command.

heroui doctor [options]

Features

Check whether have redundant dependencies in the project
Check whether the HeroUI components required dependencies are installed in the project
Check the required tailwind.config.js file and the content is correct
Check .npmrc is correct when using pnpm
Check peerDependencies with required version are installed in the project

Doctor Options

-p --packagePath string The path to the package.json file
-tw --tailwindPath string The path to the tailwind.config file file
-app --appPath string The path to the App.tsx file
-ca --checkApp boolean Open check App (default: true)
-ct --checkTailwind boolean Open check tailwind.config file (default: true)
-cp --checkPnpm boolean Open check Pnpm (default: true)

Example

heroui doctor

Output:

If there is a problem in your project, the doctor command will display the problem information.

HeroUI CLI v0.2.1

HeroUI CLI: ❌ Your project has 1 issue that require attention

❗️Issue 1: missingTailwind

Missing tailwind.config.(j|t)s file. To set up, visit: https://heroui.com/docs/guide/installation#tailwind-css-setup

Otherwise, the doctor command will display the following message.

HeroUI CLI v0.2.1

✅ Your project has no detected issues.

Env

Display debug information about the local environment.

heroui env [options]

Env Options

-p --packagePath string The path to the package.json file

Example

Display the local environment Information by using the env command.

heroui env

Output:

HeroUI CLI v0.2.1

Current installed components:

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   Package                    │   Version              │   Status    │   Docs                                              │
│───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│
│   @heroui/autocomplete   │   2.0.10 🚀latest      │   stable    │   https://heroui.com/docs/components/autocomplete   │
│   @heroui/badge          │   2.0.24 🚀latest      │   stable    │   https://heroui.com/docs/components/badge          │
│   @heroui/button         │   2.0.27 🚀latest      │   stable    │   https://heroui.com/docs/components/button         │
│   @heroui/chip           │   2.0.25 🚀latest      │   stable    │   https://heroui.com/docs/components/chip           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Environment Info:
  System:
    OS: darwin
    CPU: arm64
  Binaries:
    Node: v18.18.2

Documentation

Visit https://heroui.com/docs/guide/cli to view the full documentation.

Community

We're excited to see the community adopt HeroUI CLI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!

Contributing

Contributions are always welcome!

See CONTRIBUTING.md for ways to get started.

Please adhere to this project's CODE_OF_CONDUCT.

License

MIT

UI CLI Tool NextUI Template Integration Add Component HeroUI

@clack/prompts @winches/prompts async-retry chalk commander compare-versions fast-glob find-up gradient-string ora pathe tar

10 months ago

10 months ago

10 months ago

10 months ago