注意

你不需要 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：

{
  "dependencies": {
    "tailwindcss": "^4",
    "bun-plugin-tailwind": "latest"
  }
}

我們還會配置 bunfig.toml 使用 Bun 的 TailwindCSS 插件與 Bun.serve()

[serve.static]
plugins = ["bun-plugin-tailwind"]

以及一個 ${component}.css 文件，頂部有 @import "tailwindcss";：

@import "tailwindcss";

在 Bun 中使用 shadcn/ui

shadcn/ui 是一個極其流行的用於構建 Web 應用程序的組件庫工具。

bun create <component> 會掃描從 @/components/ui 導入的任何 shadcn/ui 組件。

如果找到，它會運行：

# 假設 bun 檢測到從 @/components/ui/accordion 和 @/components/ui/button 的導入
bunx shadcn@canary add accordion button # 以及任何其他組件

由於 shadcn/ui 本身使用 TailwindCSS，bun create 還會將必要的 TailwindCSS 依賴添加到你的 package.json 並配置 bunfig.toml 使用 Bun 的 TailwindCSS 插件與 Bun.serve()，如上所述。

此外，我們還會設置以下內容：

• 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

bun create <template> [<destination>]

假設你沒有同名的 本地模板，此命令將從 npm 下載並執行 create-<template> 包。以下兩個命令的行為相同：

bun create remix
bunx create-remix

有關完整文檔和用法，請參閱相關 create-<template> 包的文檔。

從 GitHub

這會將 GitHub 倉庫的內容下載到磁盤。

bun create <user>/<repo>
bun create github.com/<user>/<repo>

可選地指定目標文件夾的名稱。如果未指定目標，將使用倉庫名稱。

bun create <user>/<repo> mydir
bun create github.com/<user>/<repo> mydir

Bun 將執行以下步驟：

• 下載模板
• 將所有模板文件復制到目標文件夾
• 使用 bun install 安裝依賴。
• 初始化一個新的 Git 倉庫。使用 --no-git 標志選擇不執行。
• 運行模板配置的 start 腳本（如果已定義）。

NOTE

默認情況下，Bun 不會覆蓋任何現有文件。使用 `--force` 標志覆蓋現有文件。

從本地模板

警告

與遠程模板不同，使用本地模板運行 bun create 會刪除整個目標文件夾（如果已存在）！請小心。

Bun 的模板器可以擴展以支持在本地文件系統中定義的自定義模板。這些模板應位於以下目錄之一：

• $HOME/.bun-create/<name>：全局模板
• <project root>/.bun-create/<name>：項目特定的模板

注意

你可以通過設置 BUN_CREATE_DIR 環境變量來自定義全局模板路徑。

要創建本地模板，導航到 $HOME/.bun-create 並創建一個以模板名稱命名的新目錄。

cd $HOME/.bun-create
mkdir foo
cd foo

然後，在該目錄中創建一個 package.json 文件，內容如下：

{
  "name": "foo"
}

你可以在文件系統的其他地方運行 bun create foo 來驗證 Bun 是否正確找到你的本地模板。

設置邏輯

你可以在本地模板的 package.json 的 "bun-create" 部分中指定安裝前和安裝後的設置腳本。

{
  "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 優先於 GITHUB_ACCESS_TOKEN。

bun create 的工作原理

當你運行 bun create ${template} ${destination} 時，會發生以下情況：

如果是遠程模板

1. GET registry.npmjs.org/@bun-examples/${template}/latest 並解析它
2. GET registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz
3. 解壓縮和解壓 ${template}-${latestVersion}.tgz 到 ${destination}
   • 如果有會覆蓋的文件，警告並退出，除非傳遞了 --force

如果是 GitHub 倉庫

1. 從 GitHub API 下載 tarball
2. 解壓縮和解壓到 ${destination}
   • 如果有會覆蓋的文件，警告並退出，除非傳遞了 --force

否則如果是本地模板

1. 打開本地模板文件夾
2. 遞歸刪除目標目錄
3. 使用可用的最快系統調用遞歸復制文件（在 macOS 上使用 fcopyfile，在 Linux 上使用 copy_file_range）。不復制或遍歷 node_modules 文件夾（如果存在）（僅此一點就比 cp 更快）
4. 解析 package.json（再次！），將 name 更新為 ${basename(destination)}，從 package.json 中刪除 bun-create 部分，並將更新後的 package.json 保存到磁盤。
   • 如果檢測到 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. 使用 npm 客戶端運行 "bun-create": { "preinstall" } 中定義的任何任務
7. 運行 ${npmClient} install，除非傳遞了 --no-install 或 package.json 中沒有依賴
8. 使用 npm 客戶端運行 "bun-create": { "postinstall" } 中定義的任何任務
9. 運行 git init; git add -A .; git commit -am "Initial Commit";
   • 將 gitignore 重命名為 .gitignore。NPM 會自動從包中刪除 .gitignore 文件。
   • 如果有依賴，這會在安裝 node_modules 時在單獨的線程中並發運行
   • 在微基准測試中，使用 libgit2（如果可用）測試的性能慢了 3 倍