Installation

Requirements

If you haven't set up HeroUI Native OSS yet, follow the HeroUI Native Quick Start first.

Run the HeroUI Pro CLI and log in with your GitHub account:

npx heroui-pro login

bunx heroui-pro login

pnpm dlx heroui-pro login

A browser tab will open automatically. Sign in with your GitHub account, authorize the application, and wait for the terminal to confirm:

Logged in as @your-username

Install

Once logged in, run:

npx heroui-pro install

bunx heroui-pro install

pnpm dlx heroui-pro install

The CLI handles everything automatically:

Adds heroui-native-pro to your project (if not already present)
Downloads Pro components from the CDN using your license
Detects missing peer dependencies (like @internationalized/date for date components) and installs them
Configures your package manager — for pnpm and bun, offers to allowlist the postinstall script so future installs work seamlessly

After installation completes you'll see:

└  ✓ HeroUI React Native Pro v1.0.0-beta.1 installed successfully.

You can also use the interactive menu by running npx heroui-pro with no arguments. It provides a guided flow for login, installation, and account management.

Configure global.css

Add the HeroUI Native Pro source path to your global.css file so Tailwind can scan Pro component classes:

global.css

@import 'tailwindcss';
@import 'uniwind';

@import 'heroui-native/styles';
@import 'heroui-native-pro/styles'; 

@source './node_modules/heroui-native/lib';
@source './node_modules/heroui-native-pro/lib';

The @source path is relative to your global.css file. Adjust accordingly if your CSS file is not at the project root (e.g., ../node_modules/heroui-native-pro/lib if global.css is in app/).

Use a Pro Component

import { Stepper } from 'heroui-native-pro';
import { View } from 'react-native';

export default function MyComponent() {
  return (
    <View className="flex-1 justify-center bg-background p-4">
      <Stepper>
        <Stepper.Step>
          <Stepper.Rail />
          <Stepper.Content>
            <Stepper.Title>Account</Stepper.Title>
            <Stepper.Description>Create your account</Stepper.Description>
          </Stepper.Content>
        </Stepper.Step>
        <Stepper.Step>
          <Stepper.Rail />
          <Stepper.Content>
            <Stepper.Title>Profile</Stepper.Title>
            <Stepper.Description>Set up your profile</Stepper.Description>
          </Stepper.Content>
        </Stepper.Step>
      </Stepper>
    </View>
  );
}

CLI Reference

Command	Description
`heroui-pro login`	Log in with GitHub
`heroui-pro install`	Install Pro packages, peer deps, and configure your PM
`heroui-pro install --yes`	Non-interactive install (auto-accept all prompts)
`heroui-pro install --dry-run`	Preview what would be installed without executing
`heroui-pro status`	Show login and installed package info
`heroui-pro logout`	Sign out

CI/CD

For automated environments (GitHub Actions, Vercel, Netlify, EAS, etc.), use a CI/CD token instead of interactive login. Get your token from the dashboard.

Set the HEROUI_AUTH_TOKEN environment variable in your CI pipeline:

Add HEROUI_AUTH_TOKEN as a repository secret, then reference it in your workflow:

.github/workflows/build.yml

env:
  HEROUI_AUTH_TOKEN: ${{ secrets.HEROUI_AUTH_TOKEN }}

Add HEROUI_AUTH_TOKEN as an EAS secret:

eas env:create --name HEROUI_AUTH_TOKEN --value your-cicd-token --scope project --visibility secret

export HEROUI_AUTH_TOKEN=your-cicd-token
npm install

When HEROUI_AUTH_TOKEN is set, the postinstall script automatically authenticates and downloads Pro artifacts — no interactive login needed. This works with all package managers.

Use your CI/CD token for pipelines, not your personal token. CI/CD tokens are scoped to your license and can be rotated independently from the dashboard.

Verify Installation

After installation, verify everything is working:

Check that your app starts without errors
Try importing and using a Pro component like Stepper or DatePicker
Run the CLI to check your status:

npx heroui-pro status

Troubleshooting

Installation fails with permission errors

Try running the CLI with elevated permissions or check that your package manager has write access to node_modules.

pnpm or bun: postinstall didn't run

The CLI handles this automatically — heroui-pro install downloads artifacts directly and offers to configure your package.json so future installs work natively. If you prefer to configure it manually:

bun: add "trustedDependencies": ["heroui-pro", "heroui-native-pro"] to package.json
pnpm: add "pnpm": { "onlyBuiltDependencies": ["heroui-pro", "heroui-native-pro"] } to package.json

Yarn Berry (PnP) not supported

HeroUI Pro requires node_modules. If using Yarn Berry, add nodeLinker: node-modules to your .yarnrc.yml.

Authentication expired

Run npx heroui-pro login to re-authenticate. Sessions are valid for 180 days.

Still having issues? Contact support@heroui.pro or reach out via live chat at heroui.pro/dashboard.

What's Next?

Browse Components — See all available Pro components
Provider — Configure the HeroUI Native provider for your app
Agent Skills — Set up AI tools for HeroUI Native Pro development

On this page