Bun

bun create

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.

Template a new Bun project with bun create. This is a flexible command that can be used to create a new project with 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.

From npm

bun create <template> [<destination>]

Assuming you don't have 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:

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.

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.

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.

By default Bun will not overwrite any existing files. Use the --force flag to overwrite existing files.

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.

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.

To create a local template, navigate to $HOME/.bun-create and create a new directory with the desired name of your template.

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

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

{
  "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.

{
  "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.

postinstallruns after installing dependencies
preinstallruns 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

FlagDescription
--forceOverwrite existing files
--no-installSkip installing node_modules & tasks
--no-gitDon’t initialize a git repository
--openStart & open in-browser after finish

Environment variables

NameDescription
GITHUB_API_DOMAINIf 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.

How bun create works