mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
docs: rearranged cli/runtime related sections (#6275)
* docs: rearranged cli/runtime related sections * docs: update README.md for the updated docs path * Updates * Rearrange * Rearrange * Add files * readme --------- Co-authored-by: Colin McDonnell <colinmcd94@gmail.com>
This commit is contained in:
cyfung1031
@@ -93,8 +93,8 @@ bun upgrade --canary
|
||||
- [`bun run`](https://bun.sh/docs/cli/run)
|
||||
- [`bun install`](https://bun.sh/docs/cli/install)
|
||||
- [`bun test`](https://bun.sh/docs/cli/test)
|
||||
- [`bun init`](https://bun.sh/docs/templates#bun-init)
|
||||
- [`bun create`](https://bun.sh/docs/templates#bun-create)
|
||||
- [`bun init`](https://bun.sh/docs/cli/init)
|
||||
- [`bun create`](https://bun.sh/docs/cli/bun-create)
|
||||
- [`bunx`](https://bun.sh/docs/cli/bunx)
|
||||
- Runtime
|
||||
- [Runtime](https://bun.sh/docs/runtime/index)
|
||||
|
||||
@@ -1,36 +1,12 @@
|
||||
## `bun init`
|
||||
|
||||
Scaffold an empty project with the interactive `bun init` command.
|
||||
|
||||
```bash
|
||||
$ 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`
|
||||
|
||||
{% callout %}
|
||||
**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.
|
||||
{% /callout %}
|
||||
|
||||
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.
|
||||
|
||||
### From `npm`
|
||||
If you're looking to create a brand new empty project, use [`bun init`](/docs/cli/init).
|
||||
|
||||
## From `npm`
|
||||
|
||||
```sh
|
||||
$ bun create <template> [<destination>]
|
||||
@@ -45,7 +21,7 @@ $ bunx create-remix
|
||||
|
||||
Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions.
|
||||
|
||||
### From GitHub
|
||||
## From GitHub
|
||||
|
||||
This will download the contents of the GitHub repo to disk.
|
||||
|
||||
@@ -115,7 +91,7 @@ $ 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. -->
|
||||
|
||||
### From a local template
|
||||
## From a local template
|
||||
|
||||
{% callout %}
|
||||
**⚠️ Warning** — Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it already exists! Be careful.
|
||||
@@ -1,256 +0,0 @@
|
||||
## `bun init`
|
||||
|
||||
Scaffold an empty project with `bun init`. It's an interactive tool.
|
||||
|
||||
```bash
|
||||
$ 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`.
|
||||
|
||||
```bash
|
||||
$ bun create <template> <destination>
|
||||
```
|
||||
|
||||
{% callout %}
|
||||
**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.
|
||||
{% /callout %}
|
||||
|
||||
A template can take a number of forms:
|
||||
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
```bash
|
||||
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](https://github.com/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.
|
||||
|
||||
```bash
|
||||
$ bun create
|
||||
Welcome to bun! Create a new project by pasting any of the following:
|
||||
<list of templates>
|
||||
```
|
||||
|
||||
{% callout %}
|
||||
⚡️ **Speed** — At the time of writing, `bun create react app` runs ~11x faster on a M1 Macbook Pro than `yarn create react-app app`.
|
||||
{% /callout %} -->
|
||||
|
||||
## GitHub repos
|
||||
|
||||
A template of the form `<username>/<repo>` will be downloaded from GitHub.
|
||||
|
||||
```bash
|
||||
$ bun create ahfarmer/calculator ./myapp
|
||||
```
|
||||
|
||||
Complete GitHub URLs will also work:
|
||||
|
||||
```bash
|
||||
$ 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`). Unlike `git clone` it doesn't download the commit history or configure a remote.
|
||||
|
||||
## Local templates
|
||||
|
||||
{% callout %}
|
||||
**⚠️ Warning** — Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it already exists! Be careful.
|
||||
{% /callout %}
|
||||
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
|
||||
|
||||
{% callout %}
|
||||
**Note** — You can customize the global template path by setting the `BUN_CREATE_DIR` environment variable.
|
||||
{% /callout %}
|
||||
|
||||
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
|
||||
{
|
||||
"name": "foo"
|
||||
}
|
||||
```
|
||||
|
||||
You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template.
|
||||
|
||||
{% table %}
|
||||
|
||||
---
|
||||
|
||||
- `postinstall`
|
||||
- runs after installing dependencies
|
||||
|
||||
---
|
||||
|
||||
- `preinstall`
|
||||
- runs before installing dependencies
|
||||
|
||||
<!-- ---
|
||||
|
||||
- `start`
|
||||
- a command to auto-start the application -->
|
||||
|
||||
{% /table %}
|
||||
|
||||
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:
|
||||
|
||||
```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!'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
{% table %}
|
||||
|
||||
- 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
|
||||
|
||||
{% /table %}
|
||||
|
||||
### Environment variables
|
||||
|
||||
{% table %}
|
||||
|
||||
- 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
|
||||
|
||||
{% /table %}
|
||||
|
||||
{% details summary="How `bun create` works" %}
|
||||
|
||||
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": { "preinstall" }` 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
|
||||
|
||||
{% /details %}
|
||||
@@ -1,3 +1,27 @@
|
||||
Scaffold an empty Bun project with the interactive `bun init` command.
|
||||
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
{% details summary="How `bun init` works" %}
|
||||
|
||||
`bun init` is a quick way to start a blank project with Bun. It guesses with sane defaults and is non-destructive when run multiple times.
|
||||
|
||||
|
||||
@@ -13,6 +37,4 @@ If you pass `-y` or `--yes`, it will assume you want to continue without asking
|
||||
|
||||
At the end, it runs `bun install` to install `bun-types`.
|
||||
|
||||
#### How is `bun init` different than `bun create`?
|
||||
|
||||
`bun init` is for blank projects. `bun create` applies templates.
|
||||
{% /details %}
|
||||
@@ -142,7 +142,20 @@ This will add the following to your `package.json`:
|
||||
}
|
||||
```
|
||||
|
||||
To install a package globally:
|
||||
To view a complete list of options for this command:
|
||||
|
||||
```bash
|
||||
$ bun add --help
|
||||
```
|
||||
|
||||
## `bun add --global`
|
||||
|
||||
{% callout %}
|
||||
**Note** — This would not modify package.json of your current project folder.
|
||||
**Alias** - `bun add --global`, `bun add -g`, `bun install --global` and `bun install -g`
|
||||
{% /callout %}
|
||||
|
||||
To install a package globally, use the `-g`/`--global` flag. This will not modify the `package.json` of your current project. Typically this is used for installing command-line tools.
|
||||
|
||||
```bash
|
||||
$ bun add --global cowsay # or `bun add -g cowsay`
|
||||
@@ -169,11 +182,6 @@ globalBinDir = "~/.bun/bin"
|
||||
```
|
||||
|
||||
{% /details %}
|
||||
To view a complete list of options for a given command:
|
||||
|
||||
```bash
|
||||
$ bun add --help
|
||||
```
|
||||
|
||||
## `bun remove`
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Get started with one of the quick links below, or read on to learn more about Bu
|
||||
{% arrowbutton href="/docs/installation" text="Install Bun" /%}
|
||||
{% arrowbutton href="/docs/quickstart" text="Do the quickstart" /%}
|
||||
{% arrowbutton href="/docs/cli/install" text="Install a package" /%}
|
||||
{% arrowbutton href="/docs/templates" text="Use a project template" /%}
|
||||
{% arrowbutton href="/docs/cli/bun-create" text="Use a project template" /%}
|
||||
{% arrowbutton href="/docs/bundler" text="Bundle code for production" /%}
|
||||
{% arrowbutton href="/docs/api/http" text="Build an HTTP server" /%}
|
||||
{% arrowbutton href="/docs/api/websockets" text="Build a Websocket server" /%}
|
||||
@@ -37,11 +37,14 @@ Get started with one of the quick links below, or read on to learn more about Bu
|
||||
|
||||
## What is a runtime?
|
||||
|
||||
JavaScript (or, more formally, ECMAScript) is just a _specification_ for a programming language. Anyone can write a JavaScript _engine_ that ingests a valid JavaScript program and executes it. The two most popular engines in use today are V8 (developed by Google) and JavaScriptCore (developed by Apple). Both are open source.
|
||||
JavaScript (or, more formally, ECMAScript) is just a _specification_ for a programming language. Anyone can write a JavaScript _engine_ that ingests a valid JavaScript program and executes it. The two most popular engines in use today are V8 (developed by Google)
|
||||
and JavaScriptCore (developed by Apple). Both are open source.
|
||||
|
||||
But most JavaScript programs don't run in a vacuum. They need a way to access the outside world to perform useful tasks. This is where _runtimes_ come in. They implement additional APIs that are then made available to the JavaScript programs they execute.
|
||||
|
||||
### Browsers
|
||||
|
||||
But most JavaScript programs don't run in a vacuum. They need a way to access the outside world to perform useful tasks. This is where _runtimes_ come in. They implement additional APIs that are then made available to the JavaScript programs they execute. Notably, browsers ship with JavaScript runtimes that implement a set of Web-specific APIs that are exposed via the global `window` object. Any JavaScript code executed by the browser can use these APIs to implement interactive or dynamic behavior in the context of the current webpage.
|
||||
Notably, browsers ship with JavaScript runtimes that implement a set of Web-specific APIs that are exposed via the global `window` object. Any JavaScript code executed by the browser can use these APIs to implement interactive or dynamic behavior in the context of the current webpage.
|
||||
|
||||
<!-- JavaScript runtime that exposes JavaScript engines are designed to run "vanilla" JavaScript programs, but it's often JavaScript _runtimes_ use an engine internally to execute the code and implement additional APIs that are then made available to executed programs.
|
||||
JavaScript was [initially designed](https://en.wikipedia.org/wiki/JavaScript) as a language to run in web browsers to implement interactivity and dynamic behavior in web pages. Browsers are the first JavaScript runtimes. JavaScript programs that are executed in browsers have access to a set of Web-specific global APIs on the `window` object. -->
|
||||
|
||||
@@ -67,6 +67,58 @@ $ docker pull oven/bun:alpine
|
||||
$ docker pull oven/bun:distroless
|
||||
```
|
||||
|
||||
## Checking installation
|
||||
|
||||
To check that Bun was installed successfully, run `bun --version`.
|
||||
|
||||
```sh
|
||||
$ bun --version
|
||||
1.x.y
|
||||
```
|
||||
|
||||
To see the precise commit of [oven-sh/bun](https://github.com/oven-sh/bun) that you're using, run `bun --revision`.
|
||||
|
||||
```sh
|
||||
$ bun --revision
|
||||
1.x.y+b7982ac1318937560f38e0f8eb18f45eaa43480f
|
||||
```
|
||||
|
||||
{% details summary="Troubleshoot: command not found" %}
|
||||
**Note** — If you've installed Bun but are seeing a `command not found` error, you may have to manually add the installation directory to your `PATH`. In order for this change to persist across restarts, you'll need to update the configuration file for your system's shell.
|
||||
|
||||
To detect your current shell:
|
||||
|
||||
```sh
|
||||
$ echo $SHELL
|
||||
/bin/zsh # or /bin/bash or /bin/fish
|
||||
```
|
||||
|
||||
Then add these lines to the appropriate file, save it, and open a new shell.
|
||||
|
||||
{% codetabs %}
|
||||
|
||||
```bash#bash
|
||||
# ~/.bashrc
|
||||
export BUN_INSTALL="$HOME/.bun"
|
||||
export PATH="$BUN_INSTALL/bin:$PATH"
|
||||
```
|
||||
|
||||
```bash#zsh
|
||||
# ~/.zshrc
|
||||
export BUN_INSTALL="$HOME/.bun"
|
||||
export PATH="$BUN_INSTALL/bin:$PATH"
|
||||
```
|
||||
|
||||
```sh#fish
|
||||
# ~/.config/fish/config.fish
|
||||
export BUN_INSTALL="$HOME/.bun"
|
||||
export PATH="$BUN_INSTALL/bin:$PATH"
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
{% /details %}
|
||||
|
||||
## Upgrading
|
||||
|
||||
Once installed, the binary can upgrade itself.
|
||||
|
||||
12
docs/nav.ts
12
docs/nav.ts
@@ -38,12 +38,13 @@ export default {
|
||||
page("typescript", "TypeScript", {
|
||||
description: "Install and configure type declarations for Bun's APIs",
|
||||
}),
|
||||
page("templates", "Templates", {
|
||||
description: "Hit the ground running with one of Bun's official templates, or download a template from GitHub.",
|
||||
|
||||
divider("Scaffolding"),
|
||||
page("cli/init", "`bun init`", {
|
||||
description: "Scaffold an empty Bun project.",
|
||||
}),
|
||||
page("guides", "Guides", {
|
||||
description: "A set of walkthrough guides and code snippets for performing common tasks with Bun",
|
||||
href: "/guides",
|
||||
page("cli/bun-create", "`bun create`", {
|
||||
description: "Scaffold a new Bun project from an official template or GitHub repo.",
|
||||
}),
|
||||
|
||||
// page("typescript", "TypeScript"),
|
||||
@@ -81,7 +82,6 @@ export default {
|
||||
// page("bundev", "Dev server"),
|
||||
// page("benchmarks", "Benchmarks"),
|
||||
|
||||
// divider("Runtime"),
|
||||
divider("Runtime"),
|
||||
page("cli/run", "`bun run`", {
|
||||
description: "Use `bun run` to execute JavaScript/TypeScript files and package.json scripts.",
|
||||
|
||||
Reference in New Issue
Block a user