CollectUICollectUI

Quick Start

Install HeroUI Pro component library with hpsetup

This article was written by a human (md) and optimized by AI (mdx).

We recommend using pnpm first, as it has been tested earliest and covers more scenarios.

Other package managers are on the way, and the documentation will be updated and refined once testing is complete.

One-Step Setup

Skip the manual steps of project preparation, installing HeroUI Pro, and importing demo components — get everything done in one go.

Clone the template

npx -y degit rhywonfeong/hp-nextjs-app-template my-hp-nextjs-app
cd my-hp-nextjs-app

degit clones the repository but discards the remote git history.

Make sure p cli is installed, then run the following from any path:

p clone --degit rhywonfeong/hp-nextjs-app-template my-hp-nextjs-app

It clones the remote repository in degit mode, places it in a unified project directory (for easier management), and opens it with your IDE (defaults to cursor).

Install dependencies

npm install
pnpm install
bun install
yarn install

Run hpsetup

Install HeroUI Pro

I'm using the beta version here for development testing — please don't use the beta version (it may have more bugs). Generally, the latest version is the way to go.

Also, this was restored from the local cache (dependency packages of the same version are fixed, and the official cache is also used). If it's not in the local cache, it will be pulled from the CDN.

Start the preview

npm run dev
pnpm dev
bun dev
yarn dev

When developing based on the HeroUI Pro template, the steps of installing dependencies, running hpsetup, and starting the preview are similar to the above.

Manual Installation

Project Preparation

Create a project

First, you need a HeroUI project.

If you're starting from scratch, you can initialize one with heroui-cli:

npx -y heroui-cli@latest init my-heroui-app

The project will be created in the directory where you run the command above. If you want to run it from any directory and still have unified management, try p cli (make sure it's installed beforehand):

p new -- npx -y heroui-cli@latest init my-heroui-app

It will place the project in a unified project directory (~/.p/projects/) and open it with your IDE (configurable, defaults to cursor).

Alternatively, you can directly clone an existing template (no interaction needed):

npx -y degit rhywonfeong/heroui-nextjs-app-template my-heroui-nextjs-app

Install dependencies

npm install
pnpm install
bun install
yarn install

Verify it runs

Start the development server and confirm the project runs correctly:

npm run dev
pnpm run dev
bun run dev
yarn dev

Verify it runs

After confirming the page renders correctly, press Ctrl+C to stop the development server.

Initialize Git (optional)

It's recommended to make an initial commit before installing HeroUI Pro, so you can easily see what changes are made afterward:

git init && git add . && git commit -m "init: heroui project"
git init; git add .; git commit -m "init: heroui project"

Install HeroUI Pro

Run hpsetup

image-20260521173332176

Import styles

Add a new line at the end of your global CSS file:

styles/globals.css
@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css";
src/styles/globals.css
@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css";
styles/globals.css
@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css";

Import a Demo Component

Create the component

components/area-chart-demo.tsx
"use client";

import {Card} from "@heroui/react";

import { ChartTooltip } from "@heroui-pro/react/chart-tooltip";
import {AreaChart} from "@heroui-pro/react/area-chart";

const revenueData = [
  {month: "Jan", revenue: 4200},
  {month: "Feb", revenue: 5800},
  {month: "Mar", revenue: 4900},
  {month: "Apr", revenue: 7200},
  {month: "May", revenue: 6100},
  {month: "Jun", revenue: 8400},
  {month: "Jul", revenue: 7800},
  {month: "Aug", revenue: 9200},
  {month: "Sep", revenue: 8600},
  {month: "Oct", revenue: 10200},
  {month: "Nov", revenue: 9800},
  {month: "Dec", revenue: 11500},
];

export default function AreaChartDemo() {
  return (
    <Card className="w-full max-w-[520px] rounded-2xl">
      <Card.Header>
        <Card.Title className="text-base">Monthly Revenue</Card.Title>
      </Card.Header>
      <Card.Content>
        <AreaChart data={revenueData} height={200}>
          <defs>
            <linearGradient id="revenue-fill" x1="0" x2="0" y1="0" y2="1">
              <stop offset="0%" stopColor="var(--chart-3)" stopOpacity={0.2} />
              <stop offset="100%" stopColor="var(--chart-3)" stopOpacity={0.02} />
            </linearGradient>
          </defs>
          <AreaChart.Grid vertical={false} />
          <AreaChart.XAxis dataKey="month" tickMargin={8} />
          <AreaChart.YAxis tickFormatter={(v: number) => `$${(v / 1000).toFixed(0)}k`} width={40} />
          <AreaChart.Area
            dataKey="revenue"
            dot={false}
            fill="url(#revenue-fill)"
            name="Revenue"
            stroke="var(--chart-3)"
            strokeWidth={2}
            type="monotone"
          />
          <AreaChart.Tooltip
            content={({active, label, payload}) => {
              if (!active || !payload?.length) return null;

              return (
                <ChartTooltip>
                  <ChartTooltip.Header>{label}</ChartTooltip.Header>
                  {payload.map((entry) => (
                    <ChartTooltip.Item key={String(entry.dataKey)}>
                      <ChartTooltip.Indicator color={entry.color ?? entry.stroke} />
                      <ChartTooltip.Label>{entry.name}</ChartTooltip.Label>
                      <ChartTooltip.Value>
                        ${Number(entry.value).toLocaleString()}
                      </ChartTooltip.Value>
                    </ChartTooltip.Item>
                  ))}
                </ChartTooltip>
              );
            }}
          />
        </AreaChart>
      </Card.Content>
    </Card>
  );
}
src/components/area-chart-demo.tsx
"use client";

import {Card} from "@heroui/react";

import { ChartTooltip } from "@heroui-pro/react/chart-tooltip";
import {AreaChart} from "@heroui-pro/react/area-chart";

const revenueData = [
  {month: "Jan", revenue: 4200},
  {month: "Feb", revenue: 5800},
  {month: "Mar", revenue: 4900},
  {month: "Apr", revenue: 7200},
  {month: "May", revenue: 6100},
  {month: "Jun", revenue: 8400},
  {month: "Jul", revenue: 7800},
  {month: "Aug", revenue: 9200},
  {month: "Sep", revenue: 8600},
  {month: "Oct", revenue: 10200},
  {month: "Nov", revenue: 9800},
  {month: "Dec", revenue: 11500},
];

export default function AreaChartDemo() {
  return (
    <Card className="w-full max-w-[520px] rounded-2xl">
      <Card.Header>
        <Card.Title className="text-base">Monthly Revenue</Card.Title>
      </Card.Header>
      <Card.Content>
        <AreaChart data={revenueData} height={200}>
          <defs>
            <linearGradient id="revenue-fill" x1="0" x2="0" y1="0" y2="1">
              <stop offset="0%" stopColor="var(--chart-3)" stopOpacity={0.2} />
              <stop offset="100%" stopColor="var(--chart-3)" stopOpacity={0.02} />
            </linearGradient>
          </defs>
          <AreaChart.Grid vertical={false} />
          <AreaChart.XAxis dataKey="month" tickMargin={8} />
          <AreaChart.YAxis tickFormatter={(v: number) => `$${(v / 1000).toFixed(0)}k`} width={40} />
          <AreaChart.Area
            dataKey="revenue"
            dot={false}
            fill="url(#revenue-fill)"
            name="Revenue"
            stroke="var(--chart-3)"
            strokeWidth={2}
            type="monotone"
          />
          <AreaChart.Tooltip
            content={({active, label, payload}) => {
              if (!active || !payload?.length) return null;

              return (
                <ChartTooltip>
                  <ChartTooltip.Header>{label}</ChartTooltip.Header>
                  {payload.map((entry) => (
                    <ChartTooltip.Item key={String(entry.dataKey)}>
                      <ChartTooltip.Indicator color={entry.color ?? entry.stroke} />
                      <ChartTooltip.Label>{entry.name}</ChartTooltip.Label>
                      <ChartTooltip.Value>
                        ${Number(entry.value).toLocaleString()}
                      </ChartTooltip.Value>
                    </ChartTooltip.Item>
                  ))}
                </ChartTooltip>
              );
            }}
          />
        </AreaChart>
      </Card.Content>
    </Card>
  );
}
components/area-chart-demo.tsx
"use client";

import {Card} from "@heroui/react";

import { ChartTooltip } from "@heroui-pro/react/chart-tooltip";
import {AreaChart} from "@heroui-pro/react/area-chart";

const revenueData = [
  {month: "Jan", revenue: 4200},
  {month: "Feb", revenue: 5800},
  {month: "Mar", revenue: 4900},
  {month: "Apr", revenue: 7200},
  {month: "May", revenue: 6100},
  {month: "Jun", revenue: 8400},
  {month: "Jul", revenue: 7800},
  {month: "Aug", revenue: 9200},
  {month: "Sep", revenue: 8600},
  {month: "Oct", revenue: 10200},
  {month: "Nov", revenue: 9800},
  {month: "Dec", revenue: 11500},
];

export default function AreaChartDemo() {
  return (
    <Card className="w-full max-w-[520px] rounded-2xl">
      <Card.Header>
        <Card.Title className="text-base">Monthly Revenue</Card.Title>
      </Card.Header>
      <Card.Content>
        <AreaChart data={revenueData} height={200}>
          <defs>
            <linearGradient id="revenue-fill" x1="0" x2="0" y1="0" y2="1">
              <stop offset="0%" stopColor="var(--chart-3)" stopOpacity={0.2} />
              <stop offset="100%" stopColor="var(--chart-3)" stopOpacity={0.02} />
            </linearGradient>
          </defs>
          <AreaChart.Grid vertical={false} />
          <AreaChart.XAxis dataKey="month" tickMargin={8} />
          <AreaChart.YAxis tickFormatter={(v: number) => `$${(v / 1000).toFixed(0)}k`} width={40} />
          <AreaChart.Area
            dataKey="revenue"
            dot={false}
            fill="url(#revenue-fill)"
            name="Revenue"
            stroke="var(--chart-3)"
            strokeWidth={2}
            type="monotone"
          />
          <AreaChart.Tooltip
            content={({active, label, payload}) => {
              if (!active || !payload?.length) return null;

              return (
                <ChartTooltip>
                  <ChartTooltip.Header>{label}</ChartTooltip.Header>
                  {payload.map((entry) => (
                    <ChartTooltip.Item key={String(entry.dataKey)}>
                      <ChartTooltip.Indicator color={entry.color ?? entry.stroke} />
                      <ChartTooltip.Label>{entry.name}</ChartTooltip.Label>
                      <ChartTooltip.Value>
                        ${Number(entry.value).toLocaleString()}
                      </ChartTooltip.Value>
                    </ChartTooltip.Item>
                  ))}
                </ChartTooltip>
              );
            }}
          />
        </AreaChart>
      </Card.Content>
    </Card>
  );
}

Import it into a page

app/page.tsx
import AreaChartDemo from "@/components/area-chart-demo";

export default function Page() {
  return <AreaChartDemo />;
}
src/App.tsx
import AreaChartDemo from "./components/area-chart-demo";

export default function Page() {
  return <AreaChartDemo />;
}
pages/index.tsx
import AreaChartDemo from "../components/area-chart-demo";

export default function Page() {
  return <AreaChartDemo />;
}

Start the preview

npm run dev
pnpm dev
bun dev
yarn dev

Start the preview

FAQ

HeroUI CLI Options

HeroUI CLI initialization options

Note that HeroUI CLI offers three options when creating a new project:

  • Options 1 and 2 are both Next.js, while option 3 is React + Vite
  • Option 2 is Next.js Pages Router, which is kept for compatibility with legacy projects. It's no longer recommended for new projects — the App Router (option 1) is the recommended choice

Installation Errors

If you encounter the [ERR_PNPM_IGNORED_BUILDS] error during install, you need to approve the builds — i.e., allow the build scripts of these dependencies to run — before you can continue.

pnpm approve-builds

Run:

pnpm approve-builds

How is this guide?

Last updated on

Agent Skills

Install HeroUI Pro skill packs for AI tools so agents write high-quality code from the start.

HeroUI Native

Initialize a HeroUI Native project

On this page

One-Step SetupManual InstallationProject PreparationInstall HeroUI ProImport a Demo ComponentFAQHeroUI CLI OptionsInstallation Errors