@buildpad/cli

中文文档

3.7.0发布于 2026/11/06MITTypeScriptES Module近 30 天下载 1901

用于在您的工程中添加 Buildpad 组件的 CLI 工具 - 如 shadcn/ ui

文档目录39 节

使用量
输入
选项
添加
选项
实例
列表
选项
拖带
选项
诱饵会做什么
验证
选项
它检查什么
示例输出
微调
选项
状态
选项
示例输出
buildpad.json (英语)
tx
曲线
别名
安装了Lib和安装了组件
获得什么复制
示例:添加 list-m2m
导入转换
构成部分类别
VForm 和收藏工具
同伴依赖关系
安装后的项目结构
CLI 命令参考
解决问题
找不到注册文件
"没有找到buildpad.json"
添加组件后导入出错
发展
许可证

@ buildpad/ cli (中文(简体) )

在您的工程中添加 Buildpad 组件的 CLI .

使用量

使用 init 命令来设置新工程和 add 命令以添加组件.

npx @buildpad/cli init
npx @buildpad/cli add input select-dropdown

输入

使用 init 命令以初始化新工程的配置和依赖.

这个 init 命令创建一个 buildpad.json 文件,设置目录结构,并检查所需的依赖性.

npx @buildpad/cli init

选项

Usage: buildpad init [options]

initialize your project and install dependencies

Options:
  -y, --yes       skip confirmation prompt (default: false)
  -c, --cwd <cwd> the working directory (defaults to current directory)
  -h, --help      display help for command

添加

使用 add 命令将添加组件到您的工程中.

npx @buildpad/cli add [component]

选项

Usage: buildpad add [options] [components...]

add components to your project

Arguments:
  components         name of components to add

Options:
  -a, --all          add all available components (default: false)
  --with-api         also add API routes and Supabase auth templates
  --category <name>  add all components from a category
  -o, --overwrite    overwrite existing files (default: false)
  -n, --dry-run      preview changes without modifying files
  --cwd <cwd>        the working directory (defaults to current directory)
  -h, --help         display help for command

实例

# Add specific components
npx @buildpad/cli add input
npx @buildpad/cli add input select-dropdown datetime

# Add collection-form (includes VForm + all 32 interface components)
npx @buildpad/cli add collection-form

# Add all components from a category
npx @buildpad/cli add --category selection

# Add all components
npx @buildpad/cli add --all

列表

使用 list 命令以查看所有可用的组件.

npx @buildpad/cli list

选项

Usage: buildpad list [options]

list available components

Options:
  --category <name>  filter by category
  --json             output as JSON
  -h, --help         display help for command

拖带

使用 bootstrap 命令用于在单一的非交互命令中设置完整的项目。建议使用AI剂和CI/CD管道.

npx @buildpad/cli bootstrap

选项

Usage: buildpad bootstrap [options]

Full project setup: init + add --all + install deps + validate (single command for AI agents)

Options:
  --cwd <cwd>          the working directory (defaults to current directory)
  --skip-deps          skip npm dependency installation
  --skip-validate      skip post-install validation
  --locales <codes>    locales for app/[lang], comma-separated (e.g. en,id); default: en
  --default-locale <code>  default locale (must be in --locales); default: the first one
  -h, --help           display help for command

诱饵会做什么

创建 buildpad.json 和项目骨架(package.json、tsconfig、 app/[lang] root 版式和主页、设计符号、语言路由 lib/i18n/(中文(简体) )
复制全部 40+ UI 组件到 components/ui/
复制类型、服务、钩子 lib/buildpad/
复制 API 代理路由( 域、项、关系、文件)
复制认证代理路由( 登录、登录、用户、回调) + 登录页面
副本 Supabase auth 公用事业和中间软件
运行 pnpm install 解决所有依赖关系
验证安装

Auth 路由已安装 :

路线	方法	目的
`/api/auth/login`	邮政	通过 Supabase Auth 登录(服务器侧,无 CORS)
`/api/auth/logout`	邮政	签名并清除会话 cookie
`/api/auth/user`	获取	获取当前用户配置
`/api/auth/callback`	获取	处理 OAuth/电子邮件确认方向
`/app/[lang]/login/page.tsx`	—— 说	使用代理模式( 本地前缀) 登录页面

验证

使用 validate 命令来检查您的 Buildpad 安装是否用于常见问题.

npx @buildpad/cli validate

选项

Usage: buildpad validate [options]

validate Buildpad installation (check imports, missing files, SSR issues)

Options:
  --json           output as JSON for CI/CD
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command

它检查什么

未转换进口 - 说吧 @buildpad/* 未转换到本地路径的导入
缺少 lib 文件 - 所需通用模块没有(类型、服务、钩子、提款机)
缺少 CSS 文件 - 丰富的文本编辑器所需的CSS(RichTextHTML.cs,IntentBlock编辑器.cs)
安全部门改革问题 - 诸如InvolutBlock编辑器等组件,在没有SSR安全包装器的情况下导出
API 路由缺失 - 田地、物品、许可的DaaS集成路线

示例输出

✗ Found 2 error(s):

  ✗ src/components/ui/input.tsx:5
    Untransformed import: import { Field } from '@buildpad/types';

  ✗ lib/buildpad/interface-registry.ts
    Missing required file for utils module

⚠ Found 1 warning(s):

  ⚠ components/ui/index.ts
    InputBlockEditor exported directly may cause SSR errors. Use input-block-editor-wrapper instead.

💡 Suggestions:

  1. Fix 2 untransformed import(s) by running: pnpm cli add --all --overwrite --cwd .
  2. Update components/ui/index.ts to export InputBlockEditor from './input-block-editor-wrapper'

微调

使用 diff 命令在添加组件之前预览更改.

npx @buildpad/cli diff [component]

选项

Usage: buildpad diff [options] <component>

preview changes before adding a component

Options:
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command

状态

使用 status 命令以查看所有已安装的 Buildpad 组件及其来源.

npx @buildpad/cli status

选项

Usage: buildpad status [options]

show installed Buildpad components and their origins

Options:
  --json           output as JSON
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command

示例输出

📦 Buildpad Status

Config file: buildpad.json
Lib modules: types, hooks, services
Components:  input, select-dropdown, list-m2m

Installed Files:

  @buildpad/ui-interfaces/input
    └─ src/components/ui/input.tsx
       v1.0.0 (2026-01-12)

  @buildpad/lib/hooks
    └─ src/lib/buildpad/hooks/useRelationM2M.ts
       v1.0.0 (2026-01-12)

Total: 15 files from Buildpad

buildpad.json (英语)

这个 buildpad.json 文件持有您的工程配置。我们用它来理解您的项目是如何设置的,以及如何为您的项目定制组件.

您可以创建 buildpad.json 通过运行 init 命令.

{
  "$schema": "https://buildpad.dev/schema.json",
  "model": "copy-own",
  "tsx": true,
  "srcDir": true,
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/buildpad"
  },
  "installedLib": [],
  "installedComponents": []
}

tx

在 TypeScript 或 JavaScript 组件中选择 .

设置此选项为 false 允许以 JavaScript 添加组件 .jsx 文件扩展名.

{
  "tsx": true | false
}

曲线

您的项目是否使用 src/ 目录结构.

{
  "srcDir": true | false
}

别名

CLI使用这些值将生成的组件放入正确的位置.

{
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/buildpad"
  }
}

您必须设置路径别名 tsconfig.json 或者说 jsconfig.json 文件 :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

安装了Lib和安装了组件

这些阵列跟踪已安装的东西。 CLI使用它们来避免重置依赖关系.

获得什么复制

当添加组件时, CLI :

复制组件来源 转到您的组件目录
需要复制的 lib 模块 (类型、服务、钩子)
转变进口 从 @buildpad/* 转到本地路径
缺少依赖关系的报告 需要安装的

示例:添加 `list-m2m`

npx @buildpad/cli add list-m2m

此副本:

components/ui/list-m2m.tsx - 构成部分
lib/buildpad/types/ - 类型定义
lib/buildpad/services/ - CRUD服务
lib/buildpad/hooks/ - 反应钩

导入转换

原件(来源):

import { useRelationM2M } from '@buildpad/hooks';
import type { M2MItem } from '@buildpad/types';

已转换( 在您的工程中) :

import { useRelationM2M } from '@/lib/buildpad/hooks';
import type { M2MItem } from '@/lib/buildpad/types';

构成部分类别

类别	构成部分
`input`	输入、文本区域、输入代码、输入锁定编辑器、标记
`selection`	选择Dropdown、SecretRadio、SectoMultipleCheckbox、SectoIcon、自动完成API、收集项目Dropdown
`datetime`	日期时间
`boolean`	布尔, 切换
`media`	文件界面、文件图像、文件、上传、颜色
`relational`	列表M2M, 列表M2O, 列表O2M, 列表M2A
`layout`	分割器、通知、分类
`rich-text`	RichTextHtml, RichTextMarkdown 软件
`collection`	VForm, 收藏工具, 收藏列表

VForm 和收藏工具

添加时 collection-form,自动包括:

表格 - 使任何字段类型的动态形式组件
32个接口组件 - 所有外地类型(输入、选择、日期、M2M、M2O等)
幻灯片模块 - 类型、服务、接线和外地接口公用事业

这是因为 collection-form 已经 registryDependencies: ["vform"] vForm 对所有接口组件都有依赖性.

同伴依赖关系

部件需要这些外部包:

核心(随时需要):

pnpm add @mantine/core @mantine/hooks react react-dom

具体构成部分:

# DateTime component
pnpm add @mantine/dates dayjs

# Icon components
pnpm add @tabler/icons-react

# File upload
pnpm add @mantine/dropzone

# CollectionForm notifications
pnpm add @mantine/notifications

# Rich text editor
pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-link

Utils( 可选的, 对于 cn () 帮助 ):

pnpm add clsx tailwind-merge

安装后的项目结构

your-project/
├── app/
│   ├── api/
│   │   ├── auth/                        # Auth proxy routes
│   │   │   ├── login/route.ts           # POST - Supabase login
│   │   │   ├── logout/route.ts          # POST - Sign out
│   │   │   ├── user/route.ts            # GET - Current user info
│   │   │   └── callback/route.ts        # GET - OAuth callback
│   │   ├── fields/[collection]/route.ts # Fields proxy
│   │   ├── items/[collection]/route.ts  # Items proxy
│   │   └── ...
│   └── login/page.tsx                   # Login page template
├── src/
│   ├── components/
│   │   └── ui/
│   │       ├── input.tsx
│   │       ├── select-dropdown.tsx
│   │       └── datetime.tsx
│   └── lib/
│       ├── buildpad/
│       │   ├── utils.ts
│       │   ├── types/
│       │   │   ├── index.ts
│       │   │   ├── core.ts
│       │   │   ├── file.ts
│       │   │   └── relations.ts
│       │   ├── services/
│       │   │   ├── index.ts
│       │   │   ├── api-request.ts
│       │   │   ├── items.ts
│       │   │   ├── fields.ts
│       │   │   └── collections.ts
│       │   └── hooks/
│       │       ├── index.ts
│       │       ├── useRelationM2M.ts
│       │       ├── useRelationM2O.ts
│       │       └── ...
│       ├── api/auth-headers.ts          # Auth header utilities
│       └── supabase/                    # Supabase client utilities
│           ├── server.ts
│           └── client.ts
├── middleware.ts                         # Auth middleware
├── buildpad.json
└── package.json

CLI 命令参考

# Initialize project
buildpad init [--yes] [--cwd <path>] [--locales en,id] [--default-locale en]

# Bootstrap full project (init + add all + deps + validate)
buildpad bootstrap [--cwd <path>] [--skip-deps] [--skip-validate] [--locales en,id] [--default-locale en]

# Move an app scaffolded before 2.3 onto locale-prefixed app/[lang] routing
buildpad migrate i18n [--cwd <path>] [--locales en,id] [--dry-run]

# Add components
buildpad add [components...] [--all] [--category <name>] [--overwrite] [--cwd <path>]

# List components
buildpad list [--category <name>] [--json]

# Preview changes
buildpad diff <component> [--cwd <path>]

# Validate installation
buildpad validate [--json] [--cwd <path>]

# Check installed components
buildpad status [--json] [--cwd <path>]

# Component info and dependency tree
buildpad info <component> [--json]
buildpad tree <component> [--json] [--depth <n>]

# Auto-fix common issues
buildpad fix [--dry-run] [--yes] [--cwd <path>]

# Check for component updates
buildpad outdated [--json] [--cwd <path>]

解决问题

找不到注册文件

确定您正在运行 Buildpad 工作空间中的 CLI , 或者对注册进行适当的配置 .

"没有找到buildpad.json"

运行 npx @buildpad/cli init 首先初始化您的项目 .

添加组件后导入出错

保证您 tsconfig.json 有正确的路径别名 :

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

发展

构建 CLI :

cd packages/cli
pnpm build

开发中运行 :

pnpm dev

本地测试 :

node dist/index.js init
node dist/index.js add input

许可证

麻省理工学院

版本与发布记录

@buildpad/cli 共发布 52 个版本，首次发布于 2026/02/27；过去 12 个月发布了 52 个版本。

版本	发布日期	距今
`3.7.0`latest	2026/11/06	3 天前
`3.6.0`	2026/11/03	6 天前
`3.5.2`	2026/11/03	6 天前
`3.5.1`	2026/11/02	7 天前
`3.5.0`	2026/10/29	11 天前
`3.4.1`	2026/10/23	17 天前

关于 @buildpad/cli 的常见问题

@buildpad/cli 是什么？

用于在您的工程中添加 Buildpad 组件的 CLI 工具 - 如 shadcn/ ui

如何安装 @buildpad/cli？

在项目目录运行 npm install @buildpad/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 buildpad，可以用 npx buildpad 直接运行。

@buildpad/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@buildpad/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@buildpad/cli 可以商用吗？

@buildpad/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@buildpad/cli 的下载量有多少？

根据 npm 官方下载统计，@buildpad/cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,901 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@buildpad/cli 还在维护吗？

最新版本 3.7.0 发布于 2026/11/06（3 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

@buildpad/cli

@ buildpad/ cli (中文(简体) )

使用量

输入

选项

添加

选项

实例

列表

选项

拖带

选项

诱饵会做什么

验证

选项

它检查什么

示例输出

微调

选项

状态

选项

示例输出

buildpad.json (英语)

tx

曲线

别名

安装了Lib和安装了组件

获得什么复制

示例:添加 list-m2m

导入转换

构成部分类别

VForm 和收藏工具

同伴依赖关系

安装后的项目结构

CLI 命令参考

解决问题

找不到注册文件

"没有找到buildpad.json"

添加组件后导入出错

发展

许可证

版本与发布记录

关于 @buildpad/cli 的常见问题

@buildpad/cli 是什么？

如何安装 @buildpad/cli？

@buildpad/cli 支持 TypeScript 吗？

@buildpad/cli 支持 ESM 还是 CommonJS？

@buildpad/cli 可以商用吗？

@buildpad/cli 的下载量有多少？

@buildpad/cli 还在维护吗？

示例:添加 `list-m2m`