已解除速率限制，全面放开。
CollectUICollectUI

快速开始

使用 hpsetup 安装 HeroUI Pro 组件库

本文由人工撰写（md），AI 优化（mdx）。

优先推荐使用 pnpm，因为它最早进行测试，覆盖的场景更多一些。

其他的包管理器也在路上，测试完成后会更新、完善文档。

一步到位

跳过手动安装的项目准备、安装 HeroUI Pro、引入 demo 组件等过程，一步到位。

克隆模板

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

degit 会克隆仓库，但丢弃远程的 git 历史。

确保已安装 p cli，然后在任意路径下执行：

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

它会以 degit 模式克隆远程仓库，放到统一的项目目录下（方便管理），并用 IDE 打开（默认 cursor）。

安装依赖

npm install
pnpm install
bun install
yarn install

运行 hpsetup

安装 HeroUI Pro

我这里是开发测试，所以用的是 beta 版本，大家不要用 beta 版本哈（可能有更多的 bug），一般用 latest 版本就好。

另外，这里是从本地缓存中恢复了（同一版本的依赖包固定，官方也会缓存）。如果本地缓存中没有的话，会从 CDN 拉取。

启动预览

npm run dev
pnpm dev
bun dev
yarn dev

手动安装

项目准备

创建项目

首先，得有一个 HeroUI 项目。

如果是从零开始的新项目，可以用 heroui-cli 进行初始化：

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

上边这个命令在哪个目录下运行，项目就会放在哪个目录下。如果希望在任意目录下运行，还能实现统一管理，可以试试 p cli（请确保提前安装）：

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

它会把项目放到统一的项目目录（~/.p/projects/），然后用 IDE（可配，默认 cursor）打开。

另外，还可以直接克隆现有的模板（无需交互）：

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

安装依赖

npm install
pnpm install
bun install
yarn install

验证运行

启动开发服务器，确认项目可以正常运行：

npm run dev
pnpm run dev
bun run dev
yarn dev

验证运行

确认页面正常显示后，按 Ctrl+C 停止开发服务器。

初始化 Git（可选）

建议在安装 HeroUI Pro 之前先提交一次，方便查看之后做了哪些变更：

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

安装 HeroUI Pro

运行 hpsetup

image-20260521173332176

引入样式

在你的全局 CSS 文件末尾新增一行：

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";

引入 demo 组件

创建组件

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>
  );
}

引入页面

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 />;
}

启动预览

npm run dev
pnpm dev
bun dev
yarn dev

启动预览

常见问题

HeroUI CLI 选项说明

HeroUI CLI 初始化选项

注意哈，HeroUI CLI 新建项目的时候会有三个选项：

  • 第 1、2 个选项都是 Next.js，第 3 个选项是 React + Vite
  • 其中第 2 个选项是 Next.js Pages Router，这个是为了兼容老项目的，现在已经不推荐使用了，新项目都推荐用 App Router（第一个选项）

安装报错

如果在 install 安装的时候报 [ERR_PNPM_IGNORED_BUILDS] 这个错误，我们需要同意构建，也就是允许这些依赖的构建脚本运行，然后才能继续。

pnpm approve-builds

运行：

pnpm approve-builds

How is this guide?

Last updated on

Agent Skills

为 AI 工具安装 HeroUI Pro 技能包，让代理从开始就写出高质量代码。

HeroUI Native

初始化一个 HeroUI Native 项目

On this page

一步到位手动安装项目准备安装 HeroUI Pro引入 demo 组件常见问题HeroUI CLI 选项说明安装报错