快速开始

初始化 Proto UI，并把组件安装到你的项目中

:::caution[预发布阶段] Proto UI 目前处于公开发布初期。本文描述的是当前的上手路径，命令和生成结构可能在 v0 发布前继续调整。:::

你可以直接通过 npx 使用 Proto UI CLI，不需要提前全局安装。

npx @proto.ui/cli --help

在你的项目根目录执行：

npx @proto.ui/cli init

初始化完成后，项目根目录会生成一个 proto-ui/ 文件夹。

一个典型结构可能像这样：

your-project/
├── src/
├── proto-ui/
│   ├── adapters/
│   ├── prototypes/
│   ├── components/
│   │   ├── react/
│   │   │   └── index.ts
│   │   └── index.ts
│   └── config.json
├── package.json
└── ...

其中：

• config.json：CLI 后续命令会读取的项目配置
• components/：当前项目可直接导入的组件入口
• adapters/、prototypes/：CLI 管理区，不作为用户导入入口

你通常不需要手动维护这些文件，CLI 会负责管理它们。

init 会默认生成 Proto UI 的样式预设文件。你需要在应用入口引入一次：

import './styles/proto-ui-style.css';

如果你的项目入口与 src/styles 的相对位置不同，请按实际路径调整。

初始化之后，就可以按组件安装 Proto UI 组件。

例如，在 React 项目中添加一个 shadcn-button：

npx @proto.ui/cli add react shadcn-button

这个命令会：

1. 识别你选择的宿主适配器（react）
2. 检查 React runtime 是否已经存在
3. 安装对应的 adapter 与 prototype package
4. 在本地完成组装
5. 生成当前项目可以直接使用的组件入口

如果你想先查看会生成什么，而不让 CLI 安装依赖，可以使用：

npx @proto.ui/cli add react shadcn-button --no-install

这会打印需要安装的 Proto UI package，并仍然生成本地组件入口。

安装完成后，你可以从生成的 host 入口导入组件：

import { Button } from '../proto-ui/components/react';

export function Demo() {
  return <Button>Click me</Button>;
}

这里使用相对路径是有意的。不同项目的路径别名和目录层级并不相同，CLI 不会默认假设你已经配置了 proto-ui/components 这样的裸导入路径。

Proto UI 的接入是按组件进行的。

你可以继续执行：

npx @proto.ui/cli add react shadcn-toggle
npx @proto.ui/cli add react shadcn-dialog

然后继续从同一个 host 入口使用它们：

import { Button, DialogRoot, Toggle } from '../proto-ui/components/react';

如果同一个项目里同时需要 React 与 Web Component，也可以分别添加：

npx @proto.ui/cli add react shadcn-button
npx @proto.ui/cli add wc shadcn-button

React 组件会从 React 子入口导出：

import { Button } from '../proto-ui/components/react';

Web Component 构造会从 Web Component 子入口导出：

import { ButtonElement } from '../proto-ui/components/wc';

proto-ui/components/index.ts 也会生成带宿主前缀或明确名称的再导出，避免多宿主场景下命名冲突。

你可以只在新功能里使用 Proto UI，也可以只替换现有项目中的一两个组件。

一个更常见的起步方式是：

1. 先初始化 Proto UI
2. 先安装一个最简单的组件（如 Button）
3. 在局部页面里试用
4. 再决定是否继续扩展

当前 CLI 的首个闭环会安装官方 prototype package，并在本地生成 component facade。

它暂时还不会把 shadcn 这类 styled prototype 的源码写入到你的项目里供你直接二次修改。这个方向已经在规划中，但不会阻塞当前 v0 的第一条上手路径。

如果你想理解它最基本是怎么工作的：

• 前往 它是怎么工作的？

如果你想判断它是否值得引入：

• 前往 Why Proto UI

如果你想进一步了解它背后的原则与边界：

• 前往 Whitepaper