文档/详细安装

详细安装

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

前置

Node.js 20+
pnpm 9+（npm / yarn 也行，示例用 pnpm）
Next.js 16+（App Router）
React 19+、React DOM 19+
Tailwind CSS v4
GitHub 账号被加进 forge-ui org 并拿到 packages 的 read 权限。找 org 管理员拉你进 team。

生成 Personal Access Token

@forge-ui/react 发在 GitHub Packages 的 forge-ui org 下，默认私有，装之前要先拿 token。

去 GitHub 的 Personal access tokens (classic) 页面，Generate new token (classic)，只勾选 read:packages 这一个 scope，过期时间按你们规定。拿到 ghp_ 开头的字符串，只会显示一次。

配 .npmrc

项目根目录新建 .npmrc，把 @forge-ui scope 指向 GitHub Packages，顺便读取 shell 里的 token：

1@forge-ui:registry=https://npm.pkg.github.com
2//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

强烈建议把 .npmrc 加进 .gitignore——虽然里面只是 token 占位符，但团队里每个人的 token 都是独立的。

注入 Token

1# 临时：放进当前 shell
2export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
3 
4# 持久：写进 ~/.zshrc 或用 direnv 的 .envrc
5# 注意不要把 token 提交进 git，.npmrc 本身也建议 gitignore

装包

1pnpm add @forge-ui/react

装成功的话，node_modules/@forge-ui/react/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/react/styles.css";
3 
4/* 让 Tailwind v4 扫 node_modules 里的组件产物，
5   不然组件用到的 bg-fg-violet、tracking-fg 之类的 utility class 都不会生成 */
6@source "../../node_modules/@forge-ui/react/dist";

Peer dependencies

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

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/react
3 
4# 升级到指定版本
5pnpm add @forge-ui/react@0.2.0

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