bun init
Scaffold an empty project with the interactive bun init
command.
bun init
bun init helps you get started with a minimal project and tries to
guess sensible defaults. Press ^C anytime to quit.
package name (quickstart):
entry point (index.ts):
Done! A package.json file was saved in the current directory.
+ index.ts
+ .gitignore
+ tsconfig.json (for editor auto-complete)
+ README.md
To get started, run:
bun run index.ts
Press enter
to accept the default answer for each prompt, or pass the -y
flag to auto-accept the defaults.
bun create
Template a new Bun project with bun create
.
bun create <template> <destination>
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.
A template can take a number of forms:
bun create <template> # an official template (remote)
bun create <username>/<repo> # a GitHub repo (remote)
bun create <local-template> # a custom template (local)
Running bun create
performs the following steps:
- Download the template (remote templates only)
- Copy all template files into the destination folder. By default Bun will not overwrite any existing files. Use the
--force
flag to overwrite existing files. - 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.
Official templates
The following official templates are available.
bun create next ./myapp
bun create react ./myapp
bun create svelte-kit ./myapp
bun create elysia ./myapp
bun create hono ./myapp
bun create kingworld ./myapp
Each of these corresponds to a directory in the bun-community/create-templates repo. If you think a major framework is missing, please open a PR there. This list will change over time as additional examples are added. To see an up-to-date list, run bun create
with no arguments.
bun create
Welcome to bun! Create a new project by pasting any of the following:
<list of templates>
⚡️ Speed — At the time of writing, bun create react app
runs ~11x faster on a M1 Macbook Pro than yarn create react-app app
.
GitHub repos
A template of the form <username>/<repo>
will be downloaded from GitHub.
bun create ahfarmer/calculator ./myapp
Complete GitHub URLs will also work:
bun create github.com/ahfarmer/calculator ./myapp
bun create https://github.com/ahfarmer/calculator ./myapp
Bun installs the files as they currently exist current default branch (usually main
or master
). Unlike git clone
it doesn't download the commit history or configure a remote.
Local templates
⚠️ 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.
postinstall | runs after installing dependencies |
preinstall | runs before installing dependencies |
Each of these can correspond to a string or array of strings. An array of commands will be executed in order. Here is an example:
{
"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!'"
}
}
When 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_API_TOKEN | This lets bun create work with private repositories or if you get rate-limited |
How bun create
works