mirror of
https://github.com/oven-sh/bun
synced 2026-02-09 10:28:47 +00:00
270 lines
11 KiB
Plaintext
270 lines
11 KiB
Plaintext
---
|
||
title: bun create
|
||
description: Create a new Bun project from a React component, a `create-<template>` npm package, a GitHub repo, or a local template
|
||
---
|
||
|
||
<Note>
|
||
You don't need `bun create` to use Bun. You don't need any configuration at all. This command exists to make getting
|
||
started a bit quicker and easier.
|
||
</Note>
|
||
|
||
---
|
||
|
||
Template a new Bun project with `bun create`. This is a flexible command that can be used to create a new project from a React component, a `create-<template>` npm package, a GitHub repo, or a local template.
|
||
|
||
If you're looking to create a brand new empty project, use [`bun init`](/runtime/templating/init).
|
||
|
||
## From a React component
|
||
|
||
`bun create ./MyComponent.tsx` turns an existing React component into a complete dev environment with hot reload and production builds in one command.
|
||
|
||
```bash
|
||
bun create ./MyComponent.jsx # .tsx also supported
|
||
```
|
||
|
||
<Frame>
|
||
<video
|
||
style={{ aspectRatio: "2062 / 1344", width: "100%", height: "100%", objectFit: "contain" }}
|
||
loop
|
||
autoPlay
|
||
muted
|
||
playsInline
|
||
>
|
||
<source
|
||
src="/images/bun-create-shadcn.mp4"
|
||
style={{ width: "100%", height: "100%", objectFit: "contain" }}
|
||
type="video/mp4"
|
||
/>
|
||
</video>
|
||
</Frame>
|
||
|
||
<Note>
|
||
🚀 **Create React App Successor** — `bun create <component>` provides everything developers loved about Create React App, but with modern tooling, faster builds, and backend support.
|
||
</Note>
|
||
|
||
#### How this works
|
||
|
||
When you run `bun create <component>`, Bun:
|
||
|
||
1. Uses [Bun's JavaScript bundler](/bundler) to analyze your module graph.
|
||
2. Collects all the dependencies needed to run the component.
|
||
3. Scans the exports of the entry point for a React component.
|
||
4. Generates a `package.json` file with the dependencies and scripts needed to run the component.
|
||
5. Installs any missing dependencies using [`bun install --only-missing`](/pm/cli/install).
|
||
6. Generates the following files:
|
||
- `${component}.html`
|
||
- `${component}.client.tsx` (entry point for the frontend)
|
||
- `${component}.css` (css file)
|
||
7. Starts a frontend dev server automatically.
|
||
|
||
### Using TailwindCSS with Bun
|
||
|
||
[TailwindCSS](https://tailwindcss.com/) is an extremely popular utility-first CSS framework used to style web applications.
|
||
|
||
When you run `bun create <component>`, Bun scans your JSX/TSX file for TailwindCSS class names (and any files it imports). If it detects TailwindCSS class names, it will add the following dependencies to your `package.json`:
|
||
|
||
```json package.json icon="file-json"
|
||
{
|
||
"dependencies": {
|
||
"tailwindcss": "^4",
|
||
"bun-plugin-tailwind": "latest"
|
||
}
|
||
}
|
||
```
|
||
|
||
We also configure `bunfig.toml` to use Bun's TailwindCSS plugin with `Bun.serve()`
|
||
|
||
```toml bunfig.toml icon="settings"
|
||
[serve.static]
|
||
plugins = ["bun-plugin-tailwind"]
|
||
```
|
||
|
||
And a `${component}.css` file with `@import "tailwindcss";` at the top:
|
||
|
||
```css MyComponent.css icon="file-code"
|
||
@import "tailwindcss";
|
||
```
|
||
|
||
### Using `shadcn/ui` with Bun
|
||
|
||
[`shadcn/ui`](https://ui.shadcn.com/) is an extremely popular component library tool for building web applications.
|
||
|
||
`bun create <component>` scans for any shadcn/ui components imported from `@/components/ui`.
|
||
|
||
If it finds any, it runs:
|
||
|
||
```bash terminal icon="terminal"
|
||
# Assuming bun detected imports to @/components/ui/accordion and @/components/ui/button
|
||
bunx shadcn@canary add accordion button # and any other components
|
||
```
|
||
|
||
Since `shadcn/ui` itself uses TailwindCSS, `bun create` also adds the necessary TailwindCSS dependencies to your `package.json` and configures `bunfig.toml` to use Bun's TailwindCSS plugin with `Bun.serve()` as described above.
|
||
|
||
Additionally, we setup the following:
|
||
|
||
- `tsconfig.json` to alias `"@/*"` to `"src/*"` or `.` (depending on if there is a `src/` directory)
|
||
- `components.json` so that shadcn/ui knows its a shadcn/ui project
|
||
- `styles/globals.css` file that configures Tailwind v4 in the way that shadcn/ui expects
|
||
- `${component}.build.ts` file that builds the component for production with `bun-plugin-tailwind` configured
|
||
|
||
`bun create ./MyComponent.jsx` is one of the easiest ways to run code generated from LLMs like [Claude](https://claude.ai) or ChatGPT locally.
|
||
|
||
## From `npm`
|
||
|
||
```sh terminal icon="terminal"
|
||
bun create <template> [<destination>]
|
||
```
|
||
|
||
Assuming you don't have a [local template](#from-a-local-template) with the same name, this command will download and execute the `create-<template>` package from npm. The following two commands will behave identically:
|
||
|
||
```sh terminal icon="terminal"
|
||
bun create remix
|
||
bunx create-remix
|
||
```
|
||
|
||
Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions.
|
||
|
||
## From GitHub
|
||
|
||
This will download the contents of the GitHub repo to disk.
|
||
|
||
```bash terminal icon="terminal"
|
||
bun create <user>/<repo>
|
||
bun create github.com/<user>/<repo>
|
||
```
|
||
|
||
Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used.
|
||
|
||
```bash terminal icon="terminal"
|
||
bun create <user>/<repo> mydir
|
||
bun create github.com/<user>/<repo> mydir
|
||
```
|
||
|
||
Bun will perform the following steps:
|
||
|
||
- Download the template
|
||
- Copy all template files into the destination folder
|
||
- Install dependencies with `bun install`.
|
||
- Initialize a fresh Git repo. Opt out with the `--no-git` flag.
|
||
- Run the template's configured `start` script, if defined.
|
||
|
||
<Note>By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files.</Note>
|
||
|
||
## From a local template
|
||
|
||
<Warning>
|
||
Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it
|
||
already exists! Be careful.
|
||
</Warning>
|
||
|
||
Bun's templater can be extended to support custom templates defined on your local file system. These templates should live in one of the following directories:
|
||
|
||
- `$HOME/.bun-create/<name>`: global templates
|
||
- `<project root>/.bun-create/<name>`: project-specific templates
|
||
|
||
<Note>You can customize the global template path by setting the `BUN_CREATE_DIR` environment variable.</Note>
|
||
|
||
To create a local template, navigate to `$HOME/.bun-create` and create a new directory with the desired name of your template.
|
||
|
||
```bash
|
||
cd $HOME/.bun-create
|
||
mkdir foo
|
||
cd foo
|
||
```
|
||
|
||
Then, create a `package.json` file in that directory with the following contents:
|
||
|
||
```json package.json icon="file-json"
|
||
{
|
||
"name": "foo"
|
||
}
|
||
```
|
||
|
||
You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template.
|
||
|
||
#### Setup logic
|
||
|
||
You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`.
|
||
|
||
```json package.json icon="file-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...'", // a single command
|
||
"postinstall": ["echo 'Done!'"], // an array of commands
|
||
"start": "bun run echo 'Hello world!'"
|
||
}
|
||
}
|
||
```
|
||
|
||
The following fields are supported. Each of these can correspond to a string or array of strings. An array of commands will be executed in order.
|
||
|
||
| Field | Description |
|
||
| ------------- | ----------------------------------- |
|
||
| `postinstall` | runs after installing dependencies |
|
||
| `preinstall` | runs before installing dependencies |
|
||
|
||
After cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder.
|
||
|
||
## Reference
|
||
|
||
### CLI flags
|
||
|
||
| Flag | Description |
|
||
| -------------- | -------------------------------------- |
|
||
| `--force` | Overwrite existing files |
|
||
| `--no-install` | Skip installing `node_modules` & tasks |
|
||
| `--no-git` | Don't initialize a git repository |
|
||
| `--open` | Start & open in-browser after finish |
|
||
|
||
### Environment variables
|
||
|
||
| Name | Description |
|
||
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `GITHUB_API_DOMAIN` | If you're using a GitHub enterprise or a proxy, you can customize the GitHub domain Bun pings for downloads |
|
||
| `GITHUB_TOKEN` (or `GITHUB_ACCESS_TOKEN`) | This lets `bun create` work with private repositories or if you get rate-limited. `GITHUB_TOKEN` is chosen over `GITHUB_ACCESS_TOKEN` if both exist. |
|
||
|
||
<Accordion title={<span>How <code>bun create</code> works</span>}>
|
||
|
||
When you run `bun create ${template} ${destination}`, here’s what happens:
|
||
|
||
IF remote template
|
||
|
||
1. GET `registry.npmjs.org/@bun-examples/${template}/latest` and parse it
|
||
2. GET `registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz`
|
||
3. Decompress & extract `${template}-${latestVersion}.tgz` into `${destination}`
|
||
- If there are files that would overwrite, warn and exit unless `--force` is passed
|
||
|
||
IF GitHub repo
|
||
|
||
1. Download the tarball from GitHub’s API
|
||
2. Decompress & extract into `${destination}`
|
||
- If there are files that would overwrite, warn and exit unless `--force` is passed
|
||
|
||
ELSE IF local template
|
||
|
||
1. Open local template folder
|
||
2. Delete destination directory recursively
|
||
3. Copy files recursively using the fastest system calls available (on macOS `fcopyfile` and Linux, `copy_file_range`). Do not copy or traverse into `node_modules` folder if exists (this alone makes it faster than `cp`)
|
||
|
||
4. Parse the `package.json` (again!), update `name` to be `${basename(destination)}`, remove the `bun-create` section from the `package.json` and save the updated `package.json` to disk.
|
||
- IF Next.js is detected, add `bun-framework-next` to the list of dependencies
|
||
- IF Create React App is detected, add the entry point in `/src/index.{js,jsx,ts,tsx}` to `public/index.html`
|
||
- IF Relay is detected, add `bun-macro-relay` so that Relay works
|
||
5. Auto-detect the npm client, preferring `pnpm`, `yarn` (v1), and lastly `npm`
|
||
6. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
|
||
7. Run `${npmClient} install` unless `--no-install` is passed OR no dependencies are in package.json
|
||
8. Run any tasks defined in `"bun-create": { "postinstall" }` with the npm client
|
||
9. Run `git init; git add -A .; git commit -am "Initial Commit";`
|
||
- Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
|
||
- If there are dependencies, this runs in a separate thread concurrently while node_modules are being installed
|
||
- Using libgit2 if available was tested and performed 3x slower in microbenchmarks
|
||
|
||
</Accordion>
|