Skip to main content
你不需要 bun create 来使用 Bun。其实你完全不需要任何配置。这个命令的存在只是为了让入门更快更简单一些。
使用 bun create 模板化一个新的 Bun 项目。这个命令非常灵活，可以用来从 React 组件、create-<template> npm 包、GitHub 仓库或本地模板创建新项目。 如果你想创建一个全新的空白项目，请使用 bun init。

​
从 React 组件创建

bun create ./MyComponent.tsx 会将已有的 React 组件转变成一个包含热重载和生产构建的一体化开发环境。 
bun create ./MyComponent.jsx # 同时支持 .tsx
🚀 Create React App 的继任者 — bun create <component> 提供了开发者们喜爱的 Create React App 体验，但配备了现代工具链、更快的构建速度以及后端支持。

​
工作原理

当你运行 bun create <component> 时，Bun 会：
  1. 使用 Bun 的 JavaScript 打包器 分析你的模块图。
  2. 收集运行该组件所需的所有依赖。
  3. 扫描入口点导出中是否存在 React 组件。
  4. 生成包含所需依赖和脚本的 package.json 文件，用来运行该组件。
  5. 使用 bun install --only-missing 安装缺失的依赖。
  6. 生成以下文件：
    • ${component}.html
    • ${component}.client.tsx（前端入口文件）
    • ${component}.css（CSS 文件）
  7. 自动启动前端开发服务器。

​
在 Bun 中使用 TailwindCSS

TailwindCSS 是一个极受欢迎的实用优先 CSS 框架，用于为 web 应用添加样式。 当你运行 bun create <component> 时，Bun 会扫描你的 JSX/TSX 文件（以及任何导入的文件）中是否有 TailwindCSS 的类名。如果检测到 TailwindCSS 类名，它会将以下依赖添加到你的 package.json 中：
package.json
{
  "dependencies": {
    "tailwindcss": "^4",
    "bun-plugin-tailwind": "latest"
  }
}
同时我们会配置 bunfig.toml，使其在 Bun.serve() 中使用 Bun 的 TailwindCSS 插件：
bunfig.toml
[serve.static]
plugins = ["bun-plugin-tailwind"]
并在 ${component}.css 文件顶部添加：
MyComponent.css
@import "tailwindcss";

​
在 Bun 中使用 shadcn/ui

shadcn/ui 是一个构建 Web 应用时极受欢迎的组件库工具。 bun create <component> 会扫描是否有任何从 @/components/ui 导入的 shadcn/ui 组件。 如果找到，它会执行：
terminal
# 假设 bun 检测到导入了 @/components/ui/accordion 和 @/components/ui/button
bunx shadcn@canary add accordion button # 以及其他组件
由于 shadcn/ui 本身使用 TailwindCSS，bun create 同样会向你的 package.json 添加必要的 TailwindCSS 依赖，并照前述方式配置 bunfig.toml 以使用 Bun 的 TailwindCSS 插件。 此外，我们还会配置以下内容：
  • tsconfig.json，将 "@/*" 别名指向 "src/*" 或 .（取决于是否存在 src/ 目录）
  • components.json，使 shadcn/ui 知道这是一个 shadcn/ui 项目
  • styles/globals.css，按照 shadcn/ui 的要求配置 Tailwind v4
  • ${component}.build.ts，配置了 bun-plugin-tailwind 用于生产构建该组件文件
bun create ./MyComponent.jsx 是运行由 LLM（如 Claude 或 ChatGPT）生成代码的最简单方式之一。

​
从 npm 创建

terminal
bun create <template> [<destination>]
假如你本地没有同名的 本地模板，此命令会从 npm 下载并执行 create-<template> 包。下面两个命令效果相同：
terminal
bun create remix
bunx create-remix
关于使用方法和完整文档，请查阅对应 create-<template> 包的说明。

​
从 GitHub 创建

此操作将从 GitHub 仓库下载内容到本地磁盘。
terminal
bun create <user>/<repo>
bun create github.com/<user>/<repo>
你也可以指定目标文件夹名称。如果不指定，则默认使用仓库名。
terminal
bun create <user>/<repo> mydir
bun create github.com/<user>/<repo> mydir
Bun 会执行以下步骤：
  • 下载模板
  • 将模板中所有文件复制到目标文件夹
  • 使用 bun install 安装依赖
  • 初始化空的 Git 仓库。若不想初始化使用 --no-git 参数。
  • 如果模板定义了 start 脚本，则执行
默认情况下，Bun 不会覆盖任何已存在的文件。使用 --force 参数可强制覆盖。

​
从本地模板创建

与远程模板不同，使用本地模板运行 bun create 会删除目标文件夹及其所有内容！请谨慎操作。
Bun 的模板功能可以扩展，支持从本地文件系统加载自定义模板。这些模板应位于以下目录之一：
  • $HOME/.bun-create/<name>：全局模板目录
  • <项目根目录>/.bun-create/<name>：项目专属模板目录
你可以通过设置环境变量 BUN_CREATE_DIR 来自定义全局模板路径。
创建本地模板时，请进入 $HOME/.bun-create 并创建一个以模板名命名的文件夹。 
cd $HOME/.bun-create
mkdir foo
cd foo
然后，在该目录下创建 package.json 文件，内容如下：
package.json
{
  "name": "foo"
}
你可以在文件系统其他地方执行 bun create foo，验证 Bun 是否能正确找到本地模板。

​
设置逻辑

你可以在本地模板的 package.json 的 "bun-create" 字段中指定安装前后运行的脚本。
package.json
{
  "name": "@bun-examples/simplereact",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "bun-create": {
    "preinstall": "echo 'Installing...'", // 单条命令
    "postinstall": ["echo 'Done!'"], // 命令数组，会依次执行
    "start": "bun run echo 'Hello world!'"
  }
}
支持以下字段，每个字段可以是字符串或者字符串数组。数组中的命令会按顺序执行。
字段描述
postinstall在安装依赖后运行
preinstall在安装依赖前运行
克隆模板后，bun create 会自动从写入目标文件夹前移除 package.json 中的 "bun-create" 部分。

​
参考

​
CLI 参数

参数描述
--force覆盖已存在的文件
--no-install跳过安装 node_modules 和相关任务
--no-git不初始化 git 仓库
--open运行完成后启动并在浏览器中打开

​
环境变量

名称描述
GITHUB_API_DOMAIN如果使用 GitHub 企业版或代理服务器，可自定义 Bun 下载时访问的 GitHub 域名。
GITHUB_TOKEN（或 GITHUB_ACCESS_TOKEN）用于让 bun create 支持私有仓库或避免速率限制。如果两个都存在，优先使用 GITHUB_TOKEN。
当你运行 bun create ${template} ${destination} 时，流程如下：如果是远程模板
  1. 请求 registry.npmjs.org/@bun-examples/${template}/latest 解析最新版本信息
  2. 请求下载 registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz
  3. 解压并提取 ${template}-${latestVersion}.tgz 到 ${destination}
    • 如存在会覆盖的文件，会提示并退出，除非传入 --force
如果是 GitHub 仓库
  1. 从 GitHub API 下载 tar 包
  2. 解压并提取到 ${destination}
    • 如存在会覆盖的文件，会提示并退出，除非传入 --force
如果是本地模板
  1. 打开本地模板文件夹
  2. 递归删除目标目录
  3. 递归复制文件，使用最快的系统调用（macOS 上为 fcopyfile，Linux 上为 copy_file_range）。且不会复制或遍历任何 node_modules 目录（这使得速度优于 cp）
  4. 重新解析 package.json，更新 name 为 ${basename(destination)}，移除 bun-create 部分，并保存。
    • 如果检测到 Next.js，添加 bun-framework-next 依赖
    • 如果检测到 Create React App，添加 /src/index.{js,jsx,ts,tsx} 入口至 public/index.html
    • 如果检测到 Relay，添加 bun-macro-relay 确保 Relay 工作
  5. 自动检测 npm 客户端，优先使用 pnpm，其次是 yarn（v1），最后是 npm
  6. 运行 "bun-create": { "preinstall" } 中定义的任务，使用检测到的 npm 客户端
  7. 运行 ${npmClient} install，除非传入 --no-install 或者 package.json 中无依赖
  8. 运行 "bun-create": { "postinstall" } 中定义的任务
  9. 运行 git init; git add -A .; git commit -am "Initial Commit";
    • 将 gitignore 文件重命名为 .gitignore。由于 npm 自动移除 .gitignore 文件，故此操作必需。
    • 如果存在依赖，这步会在安装 node_modules 线程同时并行运行。
    • 使用 libgit2 测试过，性能比此方案慢 3 倍。