diff options
Diffstat (limited to 'docs/cli')
| -rw-r--r-- | docs/cli/bun-create.md (renamed from docs/cli/create.md) | 106 | ||||
| -rw-r--r-- | docs/cli/init.md (renamed from docs/cli/bun-init.md) | 28 | ||||
| -rw-r--r-- | docs/cli/install.md | 20 |
3 files changed, 91 insertions, 63 deletions
diff --git a/docs/cli/create.md b/docs/cli/bun-create.md index d59912f2b..c5cc602b6 100644 --- a/docs/cli/create.md +++ b/docs/cli/bun-create.md @@ -1,56 +1,55 @@ -## `bun init` +{% 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 %} -Scaffold an empty project with `bun init`. It's an interactive tool. +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. -```bash -$ bun init -bun init helps you get started with a minimal project and tries to -guess sensible defaults. Press ^C anytime to quit. +If you're looking to create a brand new empty project, use [`bun init`](/docs/cli/init). + +## From `npm` -package name (quickstart): -entry point (index.ts): +```sh +$ bun create <template> [<destination>] +``` -Done! A package.json file was saved in the current directory. - + index.ts - + .gitignore - + tsconfig.json (for editor auto-complete) - + README.md +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: -To get started, run: - bun run index.ts +```sh +$ bun create remix +$ bunx create-remix ``` -Press `enter` to accept the default answer for each prompt, or pass the `-y` flag to auto-accept the defaults. +Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions. -## `bun create` +## From GitHub -Template a new Bun project with `bun create`. +This will download the contents of the GitHub repo to disk. ```bash -$ bun create <template> <destination> +$ bun create <user>/<repo> +$ bun create github.com/<user>/<repo> ``` -{% 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: +Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used. ```bash -$ bun create <template> # an official template (remote) -$ bun create <username>/<repo> # a GitHub repo (remote) -$ bun create <local-template> # a custom template (local) +$ bun create <user>/<repo> mydir +$ bun create github.com/<user>/<repo> mydir ``` -Running `bun create` performs the following steps: +Bun will perform 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. +- 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. -<!-- ## Official templates +{% callout %} +By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files. +{% /callout %} + +<!-- ### Official templates The following official templates are available. @@ -75,7 +74,7 @@ Welcome to bun! Create a new project by pasting any of the following: ⚡️ **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 +<!-- ### GitHub repos A template of the form `<username>/<repo>` will be downloaded from GitHub. @@ -90,9 +89,9 @@ $ 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. +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 +## 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. @@ -124,26 +123,9 @@ Then, create a `package.json` file in that directory with the following contents You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template. -{% table %} +#### Setup logic ---- - -- `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: +You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`. ```json { @@ -162,7 +144,23 @@ Each of these can correspond to a string or array of strings. An array of comman } ``` -When cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder. +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. + +{% table %} + +--- + +- `postinstall` +- runs after installing dependencies + +--- + +- `preinstall` +- runs before installing dependencies + +{% /table %} + +After cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder. ## Reference diff --git a/docs/cli/bun-init.md b/docs/cli/init.md index bc51614e3..f17c8e1b7 100644 --- a/docs/cli/bun-init.md +++ b/docs/cli/init.md @@ -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 %} diff --git a/docs/cli/install.md b/docs/cli/install.md index 9aafae301..3a60fb054 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -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` |