bun create

bun create is optional — Bun works without any configuration. This command exists to make getting started faster.

Template a new Bun project with bun create. It creates a project from a React component, a create-<template> npm package, a GitHub repo, or a local template. To create an empty project, use bun 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.

bun create ./MyComponent.jsx # .tsx also supported

🚀 Create React App Successor — bun create <component> provides everything developers loved about Create React App, but with modern tooling, faster builds, and backend support.

How this works

When you run bun create <component>, Bun:

Uses Bun’s JavaScript bundler to analyze your module graph.
Collects all the dependencies needed to run the component.
Scans the exports of the entry point for a React component.
Generates a package.json file with the dependencies and scripts needed to run the component.
Installs any missing dependencies using bun install --only-missing.
Generates the following files:
- ${component}.html
- ${component}.client.tsx (entry point for the frontend)
- ${component}.css
Starts a frontend dev server.

Using TailwindCSS with Bun

TailwindCSS is a utility-first CSS framework for styling 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 adds the following dependencies to your package.json:

package.json

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

Bun also configures bunfig.toml to use its TailwindCSS plugin with Bun.serve():

bunfig.toml

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

And writes a ${component}.css file with @import "tailwindcss"; at the top:

MyComponent.css

@import "tailwindcss";

Using `shadcn/ui` with Bun

shadcn/ui is a 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:

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 TailwindCSS dependencies to your package.json and configures bunfig.toml to use Bun’s TailwindCSS plugin with Bun.serve(), as described earlier. bun create also sets up:

tsconfig.json to alias "@/*" to "src/*" or . (depending on whether there is a src/ directory)
components.json so that shadcn/ui knows it’s a shadcn/ui project
styles/globals.css file that configures Tailwind v4 the way shadcn/ui expects
${component}.build.ts file that builds the component for production with bun-plugin-tailwind configured

Use bun create ./MyComponent.jsx to run code generated by LLMs like Claude or ChatGPT locally.

From `npm`

terminal

bun create <template> [<destination>]

If you don’t have a local template with the same name, this command downloads and runs the create-<template> package from npm. These two commands are equivalent:

terminal

bun create remix
bunx create-remix

Refer to the create-<template> package’s documentation for usage instructions.

From GitHub

bun create <user>/<repo> downloads the contents of the GitHub repo to disk.

terminal

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

Optionally specify a name for the destination folder. If you don’t, Bun uses the repo name.

terminal

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

Bun then:

Downloads the template
Copies all template files into the destination folder
Installs dependencies with bun install
Initializes a fresh Git repo. Opt out with the --no-git flag.
Runs the template’s configured start script, if defined

By default Bun does not overwrite existing files. Use the --force flag to overwrite them.

From a local template

Unlike remote templates, running bun create with a local template deletes the entire destination folder if it already exists.

You can define custom templates on your local file system. Put them in one of the following directories:

$HOME/.bun-create/<name>: global templates
<project root>/.bun-create/<name>: project-specific templates

Set the BUN_CREATE_DIR environment variable to change the global template path.

To create a local template, create a directory in $HOME/.bun-create named after your template.

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

Then, create a package.json file in that directory with the following contents:

package.json

{
  "name": "foo"
}

Run bun create foo elsewhere on your file system to verify that Bun finds 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.

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...'", // a single command
    "postinstall": ["echo 'Done!'"], // an array of commands
    "start": "bun run echo 'Hello world!'"
  }
}

Each field accepts a string or an array of strings. An array of commands runs in order.

Field	Description
`postinstall`	runs after installing dependencies
`preinstall`	runs before installing dependencies

After cloning a template, bun create removes 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`	The GitHub domain Bun downloads from. Set this if you use GitHub Enterprise or a proxy
`GITHUB_TOKEN` (or `GITHUB_ACCESS_TOKEN`)	Lets `bun create` access private repositories and avoid rate limits. `GITHUB_TOKEN` is chosen over `GITHUB_ACCESS_TOKEN` if both exist.

How bun create works

When you run bun create ${template} ${destination}, here’s what happens:IF remote template

GET registry.npmjs.org/@bun-examples/${template}/latest and parse it
GET registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz
Decompress & extract ${template}-${latestVersion}.tgz into ${destination}
- If files would be overwritten, warn and exit unless --force is passed

IF GitHub repo

Download the tarball from GitHub’s API
Decompress & extract into ${destination}
- If files would be overwritten, warn and exit unless --force is passed

ELSE IF local template

Open local template folder
Delete destination directory recursively
Copy files recursively using the fastest system calls available (on macOS, fcopyfile; on Linux, copy_file_range). Do not copy or traverse into the node_modules folder if it exists (this alone makes it faster than cp)
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
Auto-detect the npm client, preferring pnpm, yarn (v1), and lastly npm
Run any tasks defined in "bun-create": { "preinstall" } with the npm client
Run ${npmClient} install unless --no-install is passed OR no dependencies are in package.json
Run any tasks defined in "bun-create": { "postinstall" } with the npm client
Run git init; git add -A .; git commit -am "Initial Commit";
- Rename gitignore to .gitignore. npm strips .gitignore files from published 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

​From a React component

​How this works

​Using TailwindCSS with Bun

​Using shadcn/ui with Bun

​From npm

​From GitHub

​From a local template

​Setup logic

​Reference

​CLI flags

​Environment variables

From a React component

How this works

Using TailwindCSS with Bun

Using `shadcn/ui` with Bun

From `npm`

From GitHub

From a local template

Setup logic

Reference

CLI flags

Environment variables