> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# bun create

> 从 React 组件、`create-<template>` npm 包、GitHub 仓库或本地模板创建新的 Bun 项目

<Note>
  `bun create` 是可选的 — Bun 无需任何配置即可工作。此命令的存在是为了让入门更快。
</Note>

***

使用 `bun create` 模板化一个新的 Bun 项目。它可以从 React 组件、`create-<template>` npm 包、GitHub 仓库或本地模板创建项目。

要创建一个空项目，请使用 [`bun init`](/runtime/templating/init)。

## 从 React 组件

`bun create ./MyComponent.tsx` 将一个现有的 React 组件转化为一个完整的开发环境，一次性提供热重载和生产构建。

```bash theme={null}
bun create ./MyComponent.jsx # 也支持 .tsx
```

<Frame>
  <video style={{ aspectRatio: "2062 / 1344", width: "100%", height: "100%", objectFit: "contain" }} loop autoPlay muted playsInline>
    <source src="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/images/bun-create-shadcn.mp4?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=7751175f2869252d49283d5c76bf694e" style={{ width: "100%", height: "100%", objectFit: "contain" }} type="video/mp4" data-path="images/bun-create-shadcn.mp4" />
  </video>
</Frame>

<Note>
  🚀 **Create React App 继承者** — `bun create <component>` 提供了开发者喜爱 Create React App 的一切，但配备了现代工具、更快构建和后端支持。
</Note>

#### 工作原理

当您运行 `bun create <component>` 时，Bun：

1. 使用 [Bun 的 JavaScript 打包器](/bundler) 分析您的模块图。
2. 收集运行组件所需的所有依赖。
3. 扫描入口点的导出，寻找 React 组件。
4. 生成一个包含运行组件所需依赖和脚本的 `package.json` 文件。
5. 使用 [`bun install --only-missing`](/pm/cli/install) 安装任何缺失的依赖。
6. 生成以下文件：
   * `${component}.html`
   * `${component}.client.tsx`（前端的入口点）
   * `${component}.css`
7. 启动前端开发服务器。

### 在 Bun 中使用 TailwindCSS

[TailwindCSS](https://tailwindcss.com/) 是一个用于样式化 web 应用程序的工具优先 CSS 框架。

当您运行 `bun create <component>` 时，Bun 会扫描您的 JSX/TSX 文件中的 TailwindCSS 类名（以及它导入的任何文件）。如果检测到 TailwindCSS 类名，它会将以下依赖添加到您的 `package.json`：

```json package.json icon="file-json" theme={null}
{
  "dependencies": {
    "tailwindcss": "^4",
    "bun-plugin-tailwind": "latest"
  }
}
```

Bun 还会配置 `bunfig.toml` 以在 `Bun.serve()` 中使用其 TailwindCSS 插件：

```toml bunfig.toml icon="settings" theme={null}
[serve.static]
plugins = ["bun-plugin-tailwind"]
```

并在 `${component}.css` 文件顶部写入 `@import "tailwindcss";`：

```css MyComponent.css icon="file-code" theme={null}
@import "tailwindcss";
```

### 在 Bun 中使用 `shadcn/ui`

[`shadcn/ui`](https://ui.shadcn.com/) 是一个用于构建 web 应用程序的组件库工具。

`bun create <component>` 会扫描从 `@/components/ui` 导入的任何 shadcn/ui 组件。

如果找到了，它会运行：

```bash terminal icon="terminal" theme={null}
# 假设 bun 检测到了对 @/components/ui/accordion 和 @/components/ui/button 的导入
bunx shadcn@canary add accordion button # 以及任何其他组件
```

由于 `shadcn/ui` 本身使用 TailwindCSS，`bun create` 也会将 TailwindCSS 依赖添加到您的 `package.json` 并配置 `bunfig.toml` 以在 `Bun.serve()` 中使用 Bun 的 TailwindCSS 插件，如前所述。

`bun create` 还会设置：

* `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` 在本地运行由 [Claude](https://claude.ai) 或 ChatGPT 等 LLM 生成的代码。

## 从 `npm`

```sh terminal icon="terminal" theme={null}
bun create <template> [<destination>]
```

如果您没有同名的[本地模板](#from-a-local-template)，此命令会从 npm 下载并运行 `create-<template>` 包。以下两个命令是等价的：

```sh terminal icon="terminal" theme={null}
bun create remix
bunx create-remix
```

有关用法说明，请参考 `create-<template>` 包的文档。

## 从 GitHub

`bun create <user>/<repo>` 将 GitHub 仓库的内容下载到磁盘。

```bash terminal icon="terminal" theme={null}
bun create <user>/<repo>
bun create github.com/<user>/<repo>
```

可选地指定目标文件夹的名称。如果不指定，Bun 会使用仓库名称。

```bash terminal icon="terminal" theme={null}
bun create <user>/<repo> mydir
bun create github.com/<user>/<repo> mydir
```

然后 Bun：

* 下载模板
* 将所有模板文件复制到目标文件夹
* 使用 `bun install` 安装依赖
* 初始化一个新的 Git 仓库。使用 `--no-git` 标志退出。

<Note>默认情况下，Bun **不会覆盖**现有文件。使用 `--force` 标志覆盖它们。</Note>

## 从本地模板

<Warning>
  与远程模板不同，使用本地模板运行 `bun create` 会**删除**整个目标文件夹（如果已存在）。
</Warning>

您可以在本地文件系统上定义自定义模板。将它们放在以下目录之一：

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

<Note>设置 `BUN_CREATE_DIR` 环境变量以更改全局模板路径。</Note>

要创建本地模板，在 `$HOME/.bun-create` 中创建一个以模板名称命名的目录。

```bash theme={null}
cd $HOME/.bun-create
mkdir foo
cd foo
```

然后，在该目录中创建一个包含以下内容的 `package.json` 文件：

```json package.json icon="file-json" theme={null}
{
  "name": "foo"
}
```

在文件系统的其他地方运行 `bun create foo` 以验证 Bun 找到了您的本地模板。

#### 设置逻辑

您可以在本地模板的 `package.json` 的 `"bun-create"` 部分中指定安装前和安装后的设置脚本。

```json package.json icon="file-json" theme={null}
{
  "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`                     | Bun 下载的 GitHub 域名。如果您使用 GitHub Enterprise 或代理，请设置此项。      |
| `GITHUB_TOKEN`（或 `GITHUB_ACCESS_TOKEN`） | 让 `bun create` 访问私有仓库并避免速率限制。如果两者都存在，优先选择 `GITHUB_TOKEN`。 |

<Accordion title={<span><code>bun create</code> 的工作原理</span>}>
  当您运行 `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` 保存到磁盘。

  5. 运行 `"bun-create": { "preinstall" }` 中定义的任何任务

  6. 运行 `bun install`，除非传递了 `--no-install` 或 package.json 中没有依赖

  7. 运行 `"bun-create": { "postinstall" }` 中定义的任何任务

  8. 运行 `git init; git add -A .; git commit -am "Initial Commit";`
     * 将 `gitignore` 重命名为 `.gitignore`。npm 会从发布的包中剥离 `.gitignore` 文件。
     * 如果有依赖，这会在单独的线程中与 node\_modules 安装同时运行
     * 测试过使用 libgit2（如果可用），但在微基准测试中表现慢 3 倍
</Accordion>