Set up HeroUI Pro in your project
@heroui/react + @heroui/styles)If you haven't set up HeroUI OSS yet, follow the HeroUI Quick Start first.
Run the HeroUI Pro CLI and log in with your GitHub account:
npx heroui-pro@latest loginbunx heroui-pro@latest loginpnpm dlx heroui-pro@latest loginA 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-usernameOnce logged in, run:
npx heroui-pro@latest installbunx heroui-pro@latest installpnpm dlx heroui-pro@latest installThe CLI handles everything automatically:
@heroui-pro/react to your project (if not already present)You'll see an interactive prompt to confirm which peer dependencies to install. Press Enter to install all of them:
◆ Missing peer dependencies detected. Press Enter to install all, or uncheck to skip:
│ ↑↓ move, space select, enter confirm
│ ◼ @heroui/react (>=3.2.2)
│ ◼ @heroui/styles (>=3.2.2)
│ ◼ tailwindcss (>=4.0.0)
│ ...A handful of peers are optional and only needed by specific components — maplibre-gl (Map), @tiptap/* (Rich Text Editor), streamdown / react-markdown / marked / remark-* (Markdown), recharts (charts + KPI), embla-carousel / embla-carousel-react (Carousel), shiki (Code Block, Chat Tool), and @number-flow/react (Number Stepper). You can safely skip these if you don't use those components. See SSR and subpath imports below.
After installation completes you'll see:
└ ✓ HeroUI React Pro 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.
Add HeroUI Pro styles to your main CSS file (e.g. globals.css):
@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css"; Import order matters. Always import tailwindcss first, then @heroui/styles, then @heroui-pro/react/css.
import { Command } from '@heroui-pro/react';
function App() {
return (
<Command>
<Command.Backdrop />
<Command.Container>
<Command.Dialog>
<Command.InputGroup>
<Command.InputGroup.Input placeholder="Type a command..." />
</Command.InputGroup>
<Command.List>
<Command.Item id="profile">Profile</Command.Item>
<Command.Item id="settings">Settings</Command.Item>
<Command.Item id="logout">Logout</Command.Item>
</Command.List>
</Command.Dialog>
</Command.Container>
</Command>
);
}Most components are re-exported from the package root, so you can import them from the barrel:
import { Command, Sheet, DataGrid } from '@heroui-pro/react';Some components rely on heavy, opt-in peer dependencies and are not exported from the barrel. Import them from their subpaths instead:
import { Map } from '@heroui-pro/react/map'; // requires maplibre-gl
import { Markdown } from '@heroui-pro/react/markdown'; // requires streamdown, react-markdown, marked, remark-*
import { RichTextEditor } from '@heroui-pro/react/rich-text-editor'; // requires @tiptap/*
// Charts + KPI require recharts
import { AreaChart } from '@heroui-pro/react/area-chart';
import { BarChart } from '@heroui-pro/react/bar-chart';
import { LineChart } from '@heroui-pro/react/line-chart';
import { PieChart } from '@heroui-pro/react/pie-chart';
import { ComposedChart } from '@heroui-pro/react/composed-chart';
import { RadarChart } from '@heroui-pro/react/radar-chart';
import { RadialChart } from '@heroui-pro/react/radial-chart';
import { KPI } from '@heroui-pro/react/kpi';
import { Carousel } from '@heroui-pro/react/carousel'; // requires embla-carousel(-react)
import { CodeBlock } from '@heroui-pro/react/code-block'; // requires shiki
import { ChatTool } from '@heroui-pro/react/chat-tool'; // requires shiki (via Code Block)
import { NumberStepper } from '@heroui-pro/react/number-stepper'; // requires @number-flow/react
import { Resizable } from '@heroui-pro/react/resizable'; // requires react-resizable-panelsWhy this matters for SSR. Under server-side rendering (Next.js, TanStack Start, etc.), Node evaluates the entire imported module graph up front. If the barrel re-exported these components, a single import { Sidebar } from '@heroui-pro/react' would eagerly try to resolve maplibre-gl, @tiptap/*, streamdown, recharts, embla-carousel, shiki, and @number-flow/react — crashing at module load with Cannot find package '...' even when you never use those components. Keeping them subpath-only means you only pull in a heavy peer (and need it installed) when you actually import that component.
react-resizable-panels (used by Resizable) stays a required peer because AppLayout — a barrel component — depends on it. Resizable is still moved to a subpath for consistency, but you don't need to install anything extra beyond the standard peer set to use it.
Subpath imports also tree-shake cleanly, so they're a good default even outside SSR.
| 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 |
For automated environments (GitHub Actions, Vercel, Netlify, 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:
env:
HEROUI_AUTH_TOKEN: ${{ secrets.HEROUI_AUTH_TOKEN }}Add HEROUI_AUTH_TOKEN in your project's Environment Variables settings.
Add HEROUI_AUTH_TOKEN in Site settings → Environment variables.
export HEROUI_AUTH_TOKEN=your-cicd-token
npm installWhen 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.
After installation, verify everything is working:
Command or Sheetnpx heroui-pro statusInstallation 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:
"trustedDependencies": ["heroui-pro", "@heroui-pro/react"] to package.json"pnpm": { "onlyBuiltDependencies": ["heroui-pro", "@heroui-pro/react"] } to package.jsonYarn 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.