文档/详细安装

详细安装

逐步说明每一步在做什么、为什么。想先跑起来看效果，直接看 /docs/quick-start。

前置

Node.js 20+
pnpm 9+（npm / yarn 也行，示例用 pnpm）
Next.js 16+（App Router）
React 19+、React DOM 19+
Tailwind CSS v4

装包

1pnpm add @forge-ui-official/core

装成功的话，node_modules/@forge-ui-official/core/dist/ 里会有 js + d.ts + styles.css。

接 Tailwind

在 app/globals.css 顶部 import Tailwind 和 Forge 的 token 样式，并用 @source 让 Tailwind v4 去扫 Forge 产物目录：

1@import "tailwindcss";
2@import "@forge-ui-official/core/styles.css";
3 
4/* 让 Tailwind v4 扫 node_modules 里的组件产物，
5   不然组件用到的 bg-fg-violet、tracking-fg 之类的 utility class 都不会生成 */
6@source "../../node_modules/@forge-ui-official/core/dist";

Peer dependencies

@forge-ui-official/core 不打包以下依赖，需要你项目里自己有（版本对齐很重要）：

react >=19、react-dom >=19
tailwindcss ^4（以及 @tailwindcss/postcss）
solar-icon-set ^2
next >=15（可选，只在用到 AppLayout 等依赖 next/link 的组件时才需要）

pnpm 装完如果提示某个 peer 缺失，按提示补装。

升级

升级命令：

1# 升级到最新
2pnpm update @forge-ui-official/core
3 
4# 升级到指定版本
5pnpm add @forge-ui-official/core@0.2.0

升完重跑 pnpm dev，顺手到 /components 页点一遍新版本的组件，看有没有破坏兼容。