buildover-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BuildOver Setup

BuildOver 设置

BuildOver wraps your existing dev server with a reverse proxy + AI chat widget. You visit

localhost:<buildover-port>

instead of your original port, and a floating panel lets you ask Claude to edit your source files live with HMR.

Packages (all pulled in by the

buildover

CLI):

```
buildover
```
— CLI (
```
buildover dev
```
)
```
buildover-server
```
— auto-installed dependency
```
buildover-widget
```
— auto-installed dependency

BuildOver通过反向代理+AI聊天组件包裹你现有的开发服务器。你需要访问

localhost:<buildover-port>

而非原来的端口，通过悬浮面板你可以请求Claude结合HMR实时编辑你的源文件。

Packages（均由

buildover

CLI自动引入）：

```
buildover
```
— 命令行工具（执行
```
buildover dev
```
）
```
buildover-server
```
— 自动安装的依赖
```
buildover-widget
```
— 自动安装的依赖

Workflow

操作流程

1. Check Existing Installation

1. 检查现有安装

bash

buildover --version 2>/dev/null || npx buildover --version 2>/dev/null

bash

buildover --version 2>/dev/null || npx buildover --version 2>/dev/null

2. Install BuildOver

2. 安装BuildOver

Global (recommended):

bash

npm install -g buildover

Local dev dependency:

bash

npm install --save-dev buildover

全局安装（推荐）：

bash

npm install -g buildover

本地开发依赖安装：

bash

npm install --save-dev buildover

pnpm add -D buildover / yarn add -D buildover

undefined

undefined

3. Detect Target Port

3. 检测目标端口

Read

package.json

to find the dev port:

bash

cat package.json | grep -E '"dev"|"start"'

Common defaults if not specified:

```
3000
```
— React CRA, Next.js
```
5173
```
— Vite
```
4200
```
— Angular
```
8080
```
/
```
8000
```
— generic / Django / Flask

Ask the user to confirm if unclear.

读取

package.json

以找到开发端口：

bash

cat package.json | grep -E '"dev"|"start"'

若未指定，常见默认端口：

```
3000
```
— React CRA、Next.js
```
5173
```
— Vite
```
4200
```
— Angular
```
8080
```
/
```
8000
```
— 通用项目 / Django / Flask

若不确定，请让用户确认。

4. Configure API Key

4. 配置API密钥

bash

grep "ANTHROPIC_API_KEY" .env 2>/dev/null || echo "not set"

If missing, add to

.env

(create if needed):

ANTHROPIC_API_KEY=sk-ant-...

Get a key at https://console.anthropic.com/settings/keys.

The proxy and widget work without a key — only AI chat requires it.

bash

grep "ANTHROPIC_API_KEY" .env 2>/dev/null || echo "not set"

若缺失，添加到

.env

文件中（若不存在则创建）：

ANTHROPIC_API_KEY=sk-ant-...

可在https://console.anthropic.com/settings/keys获取密钥。

即使没有密钥，代理和组件仍可正常工作——仅AI聊天功能需要密钥。

5. Start BuildOver

5. 启动BuildOver

bash

undefined

bash

undefined

Global install:

全局安装时：

buildover dev --target <target-port> --port <buildover-port>

Local install:

本地安装时：

npx buildover dev --target <target-port> --port <buildover-port>


Default `--port` is `4100`. Use `10001` to avoid common conflicts.

**Example** (Next.js on 3000, BuildOver on 10001):
```bash
buildover dev --target 3000 --port 10001

npx buildover dev --target <target-port> --port <buildover-port>


默认`--port`为`4100`。使用`10001`可避免常见端口冲突。

**示例**（Next.js运行在3000端口，BuildOver运行在10001端口）：
```bash
buildover dev --target 3000 --port 10001

→ Open http://localhost:10001

→ 打开 http://localhost:10001

undefined

undefined

6. (Optional) Cloudflare Tunnel for Remote Access

6.（可选）通过Cloudflare Tunnel实现远程访问

If the user wants a public HTTPS URL:

bash

undefined

如果用户需要公开HTTPS地址：

bash

undefined

Install (macOS)

安装（macOS系统）

brew install cloudflared

Authenticate & create tunnel

认证并创建隧道

cloudflared tunnel login cloudflared tunnel create <tunnel-name>


Create `~/.cloudflared/config.yml`:
```yaml
tunnel: <tunnel-id>
credentials-file: /Users/<username>/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: your-subdomain.yourdomain.com
    service: http://localhost:<buildover-port>
  - service: http_status:404

bash

cloudflared tunnel run <tunnel-name>

cloudflared tunnel login cloudflared tunnel create <tunnel-name>


创建`~/.cloudflared/config.yml`文件：
```yaml
tunnel: <tunnel-id>
credentials-file: /Users/<username>/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: your-subdomain.yourdomain.com
    service: http://localhost:<buildover-port>
  - service: http_status:404

bash

cloudflared tunnel run <tunnel-name>

Verification Checklist

验证清单

No
```
⚠ No authentication configured
```
at startup → API key loaded ✓
Banner shows correct target and BuildOver URLs ✓
Opening
```
http://localhost:<buildover-port>
```
shows original site + floating chat button ✓
Sending a chat message triggers
```
[Agent]
```
logs in the server output ✓

启动时无
```
⚠ No authentication configured
```
提示 → API密钥已加载 ✓
横幅显示正确的目标地址和BuildOver地址 ✓
打开
```
http://localhost:<buildover-port>
```
显示原网站+悬浮聊天按钮 ✓
发送聊天消息会在服务器输出中触发
```
[Agent]
```
日志 ✓

Common Issues

常见问题

Issue	Fix
`EADDRINUSE` on BuildOver port	`lsof -i :<port>` → kill the process
`⚠ No authentication configured`	Add `ANTHROPIC_API_KEY` to `.env` and restart server
Chat sends but no code changes	Check server logs for `[Agent] Error` — usually auth failure
Widget not visible	Hard-refresh; check `/buildover/widget.js` returns 200
HMR not working	Start the original dev server before BuildOver

问题	解决方法
BuildOver端口出现 `EADDRINUSE` 错误	执行 `lsof -i :<port>` → 终止占用该端口的进程
出现 `⚠ No authentication configured` 提示	将 `ANTHROPIC_API_KEY` 添加到 `.env` 文件并重启服务器
发送聊天消息但无代码变更	检查服务器日志中的 `[Agent] Error` ——通常是认证失败导致
组件不可见	强制刷新页面；检查 `/buildover/widget.js` 是否返回200状态码
HMR无法工作	先启动原开发服务器，再启动BuildOver