Usage

This article is generated by CC, powered by GLM-5-turbo, based on the project source code

Prerequisites

Node.js 18+

Any package manager: npm / pnpm / yarn / bun

Yarn Berry PnP is not supported; switch to the node-modules linker

A valid API Key (starting with hp_)

Basic Usage

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

The first run enters interactive mode, where hpsetup guides you through all the steps—just follow the prompts.

A Complete Example

Assume your project is a Next.js project using pnpm:

# 1. Run hpsetup
npx -y hpsetup@latest <key>

# 2. Select a product (multi-select menu)
#    ◉ HeroUI React Pro
#    ○ HeroUI Native Pro

# 3. Detect installed packages → query latest versions → download component code

# 4. Select peer dependencies to install (all selected by default, press Enter to confirm)
#    ◉ @heroui/react
#    ◉ @heroui/styles
#    ◉ tailwindcss
#    ...

# 5. Done
# ✓ HeroUI React Pro v1.2.3 installed successfully.

On subsequent runs, if you're already on the latest version, hpsetup will show:

✓ HeroUI React Pro v1.2.3 — already on the latest version.
Nothing to do.

Specify a Product

npx -y hpsetup@latest <your_hp_key> react

pnpm dlx hpsetup@latest <your_hp_key> react

bunx hpsetup@latest <your_hp_key> react

yarn dlx hpsetup@latest <your_hp_key> react

Install only Native Pro:

npx -y hpsetup@latest <your_hp_key> native

pnpm dlx hpsetup@latest <your_hp_key> native

bunx hpsetup@latest <your_hp_key> native

yarn dlx hpsetup@latest <your_hp_key> native

Argument	Product	Package Name
`react`	HeroUI React Pro	`@heroui-pro/react`
`native`	HeroUI Native Pro	`heroui-native-pro`

If not specified, an interactive selection is shown.

Automatic Mode (CI / Scripts)

When running in a CI environment or a script, no interaction is needed:

HEROUI_KEY=<your_hp_key> npx -y hpsetup@latest

HEROUI_KEY=<your_hp_key> pnpm dlx hpsetup@latest

HEROUI_KEY=<your_hp_key> bunx hpsetup@latest

HEROUI_KEY=<your_hp_key> yarn dlx hpsetup@latest

After setting the HEROUI_KEY environment variable, hpsetup automatically skips all interactive prompts and infers which product to install from package.json.

You can also trigger it manually with `--auto`

npx -y hpsetup@latest <your_hp_key> --auto

pnpm dlx hpsetup@latest <your_hp_key> --auto

bunx hpsetup@latest <your_hp_key> --auto

yarn dlx hpsetup@latest <your_hp_key> --auto

CI environments come with the CI=true variable, which hpsetup detects automatically—no extra arguments needed.

Common Options

Option	Purpose
`--auto`	Skip interactive prompts, auto-detect and install
`--dry-run`	Only show what would be done, without making any changes
`--no-cache`	Bypass the cache and force fetching from the origin (limited to once per day)
`-h, --help`	Show help information

Preview Changes (dry-run)

Not sure what hpsetup will do? Try a dry-run first:

npx -y hpsetup@latest <your_hp_key> --dry-run

pnpm dlx hpsetup@latest <your_hp_key> --dry-run

bunx hpsetup@latest <your_hp_key> --dry-run

yarn dlx hpsetup@latest <your_hp_key> --dry-run

The output looks like:

[dry-run] Would install: @heroui-pro/react
[dry-run] Would download HeroUI React Pro v1.2.3 from CDN
[dry-run] Would install peers: @heroui/react@"^2.7.0", tailwindcss@"latest"

Force Cache Refresh

npx -y hpsetup@latest <your_hp_key> --no-cache

pnpm dlx hpsetup@latest <your_hp_key> --no-cache

bunx hpsetup@latest <your_hp_key> --no-cache

yarn dlx hpsetup@latest <your_hp_key> --no-cache

Bypass both the local cache and the CDN cache to fetch the latest package directly from the origin.

--no-cache can be used at most once per day; exceeding this limit returns a 429 error.

GitHub Actions

Store your API Key in repository Secrets and use it in your workflow:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx -y hpsetup@latest
        env:
          HEROUI_KEY: ${{ secrets.HEROUI_KEY }}

Vercel

Automatic Configuration on First Run

After detecting a Next.js project, hpsetup asks whether to write a vercel.json:

Write vercel.json with installCommand for Vercel CI? [Y/n]

After confirming, it will:

Write the installCommand into vercel.json

Add vercel.json to .gitignore (to prevent leaking your API Key)

Manual Configuration

In the Vercel dashboard:

Settings → Build & Development Settings → Install Command, enter:

npx -y hpsetup@latest

Environment Variables, add:

Name: HEROUI_KEY
Value: Your API Key

The Vercel Build environment comes with CI=true, so hpsetup automatically enters non-interactive mode.

Monorepo

hpsetup automatically detects monorepo structures (via the workspaces field or pnpm-workspace.yaml)—no extra configuration needed.

Automatic Behavior

Scans all workspaces and identifies the platform type of each (Web / Native)

React Pro is installed only into Web workspaces; Native Pro only into Native workspaces

Skips shared libraries under packages/*

Peer dependencies are scanned and installed independently per workspace

Selecting Workspaces in Interactive Mode

When multiple matching workspaces exist, a multi-select menu appears so you can choose the installation targets.

In Automatic Mode

All matching workspaces are installed without manual selection.

Package Manager

hpsetup automatically detects the package manager used by the current project:

Detection Method	Priority
Lockfile (`pnpm-lock.yaml`, `yarn.lock`, etc.)	Highest
`packageManager` field in `package.json`	Medium
`npm_config_user_agent` environment variable	Low
Default	`npm`

Special Handling per Package Manager

pnpm:

Automatically adds Pro packages to allowBuilds in pnpm-workspace.yaml

If there are pending build approvals, prompts you to run pnpm approve-builds

bun:

Automatically adds Pro packages to trustedDependencies in package.json

npm:

Automatically appends --legacy-peer-deps during installation

yarn:

Only Yarn Classic is supported; PnP is not

Local Cache

Downloaded component code is cached in the ~/.heroui/cache/ directory, organized by product and version:

~/.heroui/cache/
├── react/
│   ├── 1.0.0-beta.3/
│   └── 1.0.0-beta.4/
└── react-native/
    └── 1.0.0-beta.4/

The same version is never downloaded twice—it's restored directly from the cache.

Daily Workflow

Install

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

Update

Run the same command again. hpsetup automatically detects new versions and updates.

CI / Build

Use the HEROUI_KEY environment variable in your CI configuration to pull the latest version on every build.

Troubleshoot

Use --dry-run to see what would be executed, or --no-cache to force a fresh download.

FAQ

JSX error with pnpm + Vite

does not provide an export named 'jsx'

This is a side effect of pnpm's strict dependency isolation. pnpm organizes node_modules via symbolic links, so the react/jsx-runtime that Pro components depend on for JSX transforms may resolve to a copy bundled with the Pro package rather than the React at the project root. Vite's pre-bundling doesn't automatically handle this path difference, causing the JSX export to be missing.

Manually declare the dependencies for pre-bundling in vite.config.ts so Vite bundles them into the same module:

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react/jsx-runtime", "@heroui-pro/react"],
  },
})

This article is generated by CC, powered by GLM-5-turbo, based on the project source code

Prerequisites

Node.js 18+

Any package manager: npm / pnpm / yarn / bun

Yarn Berry PnP is not supported; switch to the node-modules linker

A valid API Key (starting with hp_)

Basic Usage

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

The first run enters interactive mode, where hpsetup guides you through all the steps—just follow the prompts.

A Complete Example

Assume your project is a Next.js project using pnpm:

# 1. Run hpsetup
npx -y hpsetup@latest <key>

# 2. Select a product (multi-select menu)
#    ◉ HeroUI React Pro
#    ○ HeroUI Native Pro

# 3. Detect installed packages → query latest versions → download component code

# 4. Select peer dependencies to install (all selected by default, press Enter to confirm)
#    ◉ @heroui/react
#    ◉ @heroui/styles
#    ◉ tailwindcss
#    ...

# 5. Done
# ✓ HeroUI React Pro v1.2.3 installed successfully.

On subsequent runs, if you're already on the latest version, hpsetup will show:

✓ HeroUI React Pro v1.2.3 — already on the latest version.
Nothing to do.

Specify a Product

npx -y hpsetup@latest <your_hp_key> react

pnpm dlx hpsetup@latest <your_hp_key> react

bunx hpsetup@latest <your_hp_key> react

yarn dlx hpsetup@latest <your_hp_key> react

Install only Native Pro:

npx -y hpsetup@latest <your_hp_key> native

pnpm dlx hpsetup@latest <your_hp_key> native

bunx hpsetup@latest <your_hp_key> native

yarn dlx hpsetup@latest <your_hp_key> native

Argument	Product	Package Name
`react`	HeroUI React Pro	`@heroui-pro/react`
`native`	HeroUI Native Pro	`heroui-native-pro`

If not specified, an interactive selection is shown.

Automatic Mode (CI / Scripts)

When running in a CI environment or a script, no interaction is needed:

HEROUI_KEY=<your_hp_key> npx -y hpsetup@latest

HEROUI_KEY=<your_hp_key> pnpm dlx hpsetup@latest

HEROUI_KEY=<your_hp_key> bunx hpsetup@latest

HEROUI_KEY=<your_hp_key> yarn dlx hpsetup@latest

After setting the HEROUI_KEY environment variable, hpsetup automatically skips all interactive prompts and infers which product to install from package.json.

You can also trigger it manually with `--auto`

npx -y hpsetup@latest <your_hp_key> --auto

pnpm dlx hpsetup@latest <your_hp_key> --auto

bunx hpsetup@latest <your_hp_key> --auto

yarn dlx hpsetup@latest <your_hp_key> --auto

CI environments come with the CI=true variable, which hpsetup detects automatically—no extra arguments needed.

Common Options

Option	Purpose
`--auto`	Skip interactive prompts, auto-detect and install
`--dry-run`	Only show what would be done, without making any changes
`--no-cache`	Bypass the cache and force fetching from the origin (limited to once per day)
`-h, --help`	Show help information

Preview Changes (dry-run)

Not sure what hpsetup will do? Try a dry-run first:

npx -y hpsetup@latest <your_hp_key> --dry-run

pnpm dlx hpsetup@latest <your_hp_key> --dry-run

bunx hpsetup@latest <your_hp_key> --dry-run

yarn dlx hpsetup@latest <your_hp_key> --dry-run

The output looks like:

[dry-run] Would install: @heroui-pro/react
[dry-run] Would download HeroUI React Pro v1.2.3 from CDN
[dry-run] Would install peers: @heroui/react@"^2.7.0", tailwindcss@"latest"

Force Cache Refresh

npx -y hpsetup@latest <your_hp_key> --no-cache

pnpm dlx hpsetup@latest <your_hp_key> --no-cache

bunx hpsetup@latest <your_hp_key> --no-cache

yarn dlx hpsetup@latest <your_hp_key> --no-cache

Bypass both the local cache and the CDN cache to fetch the latest package directly from the origin.

--no-cache can be used at most once per day; exceeding this limit returns a 429 error.

GitHub Actions

Store your API Key in repository Secrets and use it in your workflow:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx -y hpsetup@latest
        env:
          HEROUI_KEY: ${{ secrets.HEROUI_KEY }}

Vercel

Automatic Configuration on First Run

After detecting a Next.js project, hpsetup asks whether to write a vercel.json:

Write vercel.json with installCommand for Vercel CI? [Y/n]

After confirming, it will:

Write the installCommand into vercel.json

Add vercel.json to .gitignore (to prevent leaking your API Key)

Manual Configuration

In the Vercel dashboard:

Settings → Build & Development Settings → Install Command, enter:

npx -y hpsetup@latest

Environment Variables, add:

Name: HEROUI_KEY
Value: Your API Key

The Vercel Build environment comes with CI=true, so hpsetup automatically enters non-interactive mode.

Monorepo

hpsetup automatically detects monorepo structures (via the workspaces field or pnpm-workspace.yaml)—no extra configuration needed.

Automatic Behavior

Scans all workspaces and identifies the platform type of each (Web / Native)

React Pro is installed only into Web workspaces; Native Pro only into Native workspaces

Skips shared libraries under packages/*

Peer dependencies are scanned and installed independently per workspace

Selecting Workspaces in Interactive Mode

When multiple matching workspaces exist, a multi-select menu appears so you can choose the installation targets.

In Automatic Mode

All matching workspaces are installed without manual selection.

Package Manager

hpsetup automatically detects the package manager used by the current project:

Detection Method	Priority
Lockfile (`pnpm-lock.yaml`, `yarn.lock`, etc.)	Highest
`packageManager` field in `package.json`	Medium
`npm_config_user_agent` environment variable	Low
Default	`npm`

Special Handling per Package Manager

pnpm:

Automatically adds Pro packages to allowBuilds in pnpm-workspace.yaml

If there are pending build approvals, prompts you to run pnpm approve-builds

bun:

Automatically adds Pro packages to trustedDependencies in package.json

npm:

Automatically appends --legacy-peer-deps during installation

yarn:

Only Yarn Classic is supported; PnP is not

Local Cache

Downloaded component code is cached in the ~/.heroui/cache/ directory, organized by product and version:

~/.heroui/cache/
├── react/
│   ├── 1.0.0-beta.3/
│   └── 1.0.0-beta.4/
└── react-native/
    └── 1.0.0-beta.4/

The same version is never downloaded twice—it's restored directly from the cache.

Daily Workflow

Install

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

Update

Run the same command again. hpsetup automatically detects new versions and updates.

CI / Build

Use the HEROUI_KEY environment variable in your CI configuration to pull the latest version on every build.

Troubleshoot

Use --dry-run to see what would be executed, or --no-cache to force a fresh download.

FAQ

JSX error with pnpm + Vite

does not provide an export named 'jsx'

Manually declare the dependencies for pre-bundling in vite.config.ts so Vite bundles them into the same module:

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react/jsx-runtime", "@heroui-pro/react"],
  },
})

This article is generated by CC, powered by GLM-5-turbo, based on the project source code

Prerequisites

Node.js 18+

Any package manager: npm / pnpm / yarn / bun

Yarn Berry PnP is not supported; switch to the node-modules linker

A valid API Key (starting with hp_)

Basic Usage

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

The first run enters interactive mode, where hpsetup guides you through all the steps—just follow the prompts.

A Complete Example

Assume your project is a Next.js project using pnpm:

# 1. Run hpsetup
npx -y hpsetup@latest <key>

# 2. Select a product (multi-select menu)
#    ◉ HeroUI React Pro
#    ○ HeroUI Native Pro

# 3. Detect installed packages → query latest versions → download component code

# 4. Select peer dependencies to install (all selected by default, press Enter to confirm)
#    ◉ @heroui/react
#    ◉ @heroui/styles
#    ◉ tailwindcss
#    ...

# 5. Done
# ✓ HeroUI React Pro v1.2.3 installed successfully.

On subsequent runs, if you're already on the latest version, hpsetup will show:

✓ HeroUI React Pro v1.2.3 — already on the latest version.
Nothing to do.

Specify a Product

npx -y hpsetup@latest <your_hp_key> react

pnpm dlx hpsetup@latest <your_hp_key> react

bunx hpsetup@latest <your_hp_key> react

yarn dlx hpsetup@latest <your_hp_key> react

Install only Native Pro:

npx -y hpsetup@latest <your_hp_key> native

pnpm dlx hpsetup@latest <your_hp_key> native

bunx hpsetup@latest <your_hp_key> native

yarn dlx hpsetup@latest <your_hp_key> native

Argument	Product	Package Name
`react`	HeroUI React Pro	`@heroui-pro/react`
`native`	HeroUI Native Pro	`heroui-native-pro`

If not specified, an interactive selection is shown.

Automatic Mode (CI / Scripts)

When running in a CI environment or a script, no interaction is needed:

HEROUI_KEY=<your_hp_key> npx -y hpsetup@latest

HEROUI_KEY=<your_hp_key> pnpm dlx hpsetup@latest

HEROUI_KEY=<your_hp_key> bunx hpsetup@latest

HEROUI_KEY=<your_hp_key> yarn dlx hpsetup@latest

After setting the HEROUI_KEY environment variable, hpsetup automatically skips all interactive prompts and infers which product to install from package.json.

You can also trigger it manually with `--auto`

npx -y hpsetup@latest <your_hp_key> --auto

pnpm dlx hpsetup@latest <your_hp_key> --auto

bunx hpsetup@latest <your_hp_key> --auto

yarn dlx hpsetup@latest <your_hp_key> --auto

CI environments come with the CI=true variable, which hpsetup detects automatically—no extra arguments needed.

Common Options

Option	Purpose
`--auto`	Skip interactive prompts, auto-detect and install
`--dry-run`	Only show what would be done, without making any changes
`--no-cache`	Bypass the cache and force fetching from the origin (limited to once per day)
`-h, --help`	Show help information

Preview Changes (dry-run)

Not sure what hpsetup will do? Try a dry-run first:

npx -y hpsetup@latest <your_hp_key> --dry-run

pnpm dlx hpsetup@latest <your_hp_key> --dry-run

bunx hpsetup@latest <your_hp_key> --dry-run

yarn dlx hpsetup@latest <your_hp_key> --dry-run

The output looks like:

[dry-run] Would install: @heroui-pro/react
[dry-run] Would download HeroUI React Pro v1.2.3 from CDN
[dry-run] Would install peers: @heroui/react@"^2.7.0", tailwindcss@"latest"

Force Cache Refresh

npx -y hpsetup@latest <your_hp_key> --no-cache

pnpm dlx hpsetup@latest <your_hp_key> --no-cache

bunx hpsetup@latest <your_hp_key> --no-cache

yarn dlx hpsetup@latest <your_hp_key> --no-cache

Bypass both the local cache and the CDN cache to fetch the latest package directly from the origin.

--no-cache can be used at most once per day; exceeding this limit returns a 429 error.

GitHub Actions

Store your API Key in repository Secrets and use it in your workflow:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx -y hpsetup@latest
        env:
          HEROUI_KEY: ${{ secrets.HEROUI_KEY }}

Vercel

Automatic Configuration on First Run

After detecting a Next.js project, hpsetup asks whether to write a vercel.json:

Write vercel.json with installCommand for Vercel CI? [Y/n]

After confirming, it will:

Write the installCommand into vercel.json

Add vercel.json to .gitignore (to prevent leaking your API Key)

Manual Configuration

In the Vercel dashboard:

Settings → Build & Development Settings → Install Command, enter:

npx -y hpsetup@latest

Environment Variables, add:

Name: HEROUI_KEY
Value: Your API Key

The Vercel Build environment comes with CI=true, so hpsetup automatically enters non-interactive mode.

Monorepo

hpsetup automatically detects monorepo structures (via the workspaces field or pnpm-workspace.yaml)—no extra configuration needed.

Automatic Behavior

Scans all workspaces and identifies the platform type of each (Web / Native)

React Pro is installed only into Web workspaces; Native Pro only into Native workspaces

Skips shared libraries under packages/*

Peer dependencies are scanned and installed independently per workspace

Selecting Workspaces in Interactive Mode

When multiple matching workspaces exist, a multi-select menu appears so you can choose the installation targets.

In Automatic Mode

All matching workspaces are installed without manual selection.

Package Manager

hpsetup automatically detects the package manager used by the current project:

Detection Method	Priority
Lockfile (`pnpm-lock.yaml`, `yarn.lock`, etc.)	Highest
`packageManager` field in `package.json`	Medium
`npm_config_user_agent` environment variable	Low
Default	`npm`

Special Handling per Package Manager

pnpm:

Automatically adds Pro packages to allowBuilds in pnpm-workspace.yaml

If there are pending build approvals, prompts you to run pnpm approve-builds

bun:

Automatically adds Pro packages to trustedDependencies in package.json

npm:

Automatically appends --legacy-peer-deps during installation

yarn:

Only Yarn Classic is supported; PnP is not

Local Cache

Downloaded component code is cached in the ~/.heroui/cache/ directory, organized by product and version:

~/.heroui/cache/
├── react/
│   ├── 1.0.0-beta.3/
│   └── 1.0.0-beta.4/
└── react-native/
    └── 1.0.0-beta.4/

The same version is never downloaded twice—it's restored directly from the cache.

Daily Workflow

Install

npx -y hpsetup@latest <your_hp_key>

pnpm dlx hpsetup@latest <your_hp_key>

bunx hpsetup@latest <your_hp_key>

yarn dlx hpsetup@latest <your_hp_key>

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react/jsx-runtime", "@heroui-pro/react"],
  },
})

Usage

On this page

Usage

On this page

Usage

On this page