diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/cli/add.md | 155 | ||||
| -rw-r--r-- | docs/cli/bun-create.md (renamed from docs/templates.md) | 34 | ||||
| -rw-r--r-- | docs/cli/bun-install.md | 2 | ||||
| -rw-r--r-- | docs/cli/create.md | 256 | ||||
| -rw-r--r-- | docs/cli/init.md (renamed from docs/cli/bun-init.md) | 28 | ||||
| -rw-r--r-- | docs/cli/install.md | 281 | ||||
| -rw-r--r-- | docs/cli/link.md | 46 | ||||
| -rw-r--r-- | docs/cli/pm.md (renamed from docs/install/utilities.md) | 0 | ||||
| -rw-r--r-- | docs/cli/remove.md | 5 | ||||
| -rw-r--r-- | docs/cli/update.md | 7 |
10 files changed, 318 insertions, 496 deletions
diff --git a/docs/cli/add.md b/docs/cli/add.md new file mode 100644 index 000000000..4b555d5a6 --- /dev/null +++ b/docs/cli/add.md @@ -0,0 +1,155 @@ +To add a particular package: + +```bash +$ bun add preact +``` + +To specify a version, version range, or tag: + +```bash +$ bun add zod@3.20.0 +$ bun add zod@^3.0.0 +$ bun add zod@latest +``` + +## `--dev` + +{% callout %} +**Alias** — `--development`, `-d`, `-D` +{% /callout %} + +To add a package as a dev dependency (`"devDependencies"`): + +```bash +$ bun add --dev @types/react +$ bun add -d @types/react +``` + +## `--optional` + +To add a package as an optional dependency (`"optionalDependencies"`): + +```bash +$ bun add --optional lodash +``` + +## `--exact` + +To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range. + +```bash +$ bun add react --exact +$ bun add react -E +``` + +This will add the following to your `package.json`: + +```jsonc +{ + "dependencies": { + // without --exact + "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0 + + // with --exact + "react": "18.2.0" // this matches only 18.2.0 exactly + } +} +``` + +To view a complete list of options for this command: + +```bash +$ bun add --help +``` + +## `--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` +$ cowsay "Bun!" + ______ +< Bun! > + ------ + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` + +{% details summary="Configuring global installation behavior" %} + +```toml +[install] +# where `bun add --global` installs packages +globalDir = "~/.bun/install/global" + +# where globally-installed package bins are linked +globalBinDir = "~/.bun/bin" +``` + +{% /details %} + +## Trusted dependencies + +Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine. + +To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json. + +```json-diff + { + "name": "my-app", + "version": "1.0.0", ++ "trustedDependencies": ["my-trusted-package"] + } +``` + +Bun reads this field and will run lifecycle scripts for `my-trusted-package`. + +<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. --> + +## Git dependencies + +To add a dependency from a git repository: + +```bash +$ bun add git@github.com:moment/moment.git +``` + +Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more. + +```json +{ + "dependencies": { + "dayjs": "git+https://github.com/iamkun/dayjs.git", + "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21", + "moment": "git@github.com:moment/moment.git", + "zod": "github:colinhacks/zod" + } +} +``` + +## Tarball dependencies + +A package name can correspond to a publicly hosted `.tgz` file. During installation, Bun will download and install the package from the specified tarball URL, rather than from the package registry. + +```sh +$ bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz +``` + +This will add the following line to your `package.json`: + +```json#package.json +{ + "dependencies": { + "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz" + } +} +``` diff --git a/docs/templates.md b/docs/cli/bun-create.md index 5061b0aff..c5cc602b6 100644 --- a/docs/templates.md +++ b/docs/cli/bun-create.md @@ -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. diff --git a/docs/cli/bun-install.md b/docs/cli/bun-install.md index 3efe2da7f..0cbc21e1d 100644 --- a/docs/cli/bun-install.md +++ b/docs/cli/bun-install.md @@ -21,7 +21,7 @@ Configuring with `bunfig.toml` is optional. Bun tries to be zero configuration i # Scope name The value can be a URL string or an object "@mybigcompany" = { token = "123456", url = "https://registry.mybigcompany.com" } -# URL is optional and fallsback to the default registry +# URL is optional and falls back to the default registry # The "@" in the scope is optional mybigcompany2 = { token = "123456" } diff --git a/docs/cli/create.md b/docs/cli/create.md deleted file mode 100644 index d59912f2b..000000000 --- a/docs/cli/create.md +++ /dev/null @@ -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 %} 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..573a6f106 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -23,41 +23,19 @@ sudo apt install --install-recommends linux-generic-hwe-20.04 {% /details %} -## `bun install` - To install all dependencies of a project: ```bash $ bun install ``` -On Linux, `bun install` tends to install packages 20-100x faster than `npm install`. On macOS, it's more like 4-80x. - - - Running `bun install` will: - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun does not install `peerDependencies` by default. - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies. - **Write** a `bun.lockb` lockfile to the project root. -To install in production mode (i.e. without `devDependencies` or `optionalDependencies`): - -```bash -$ bun install --production -``` - -To install with reproducible dependencies, use `--frozen-lockfile`. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. This is useful for production builds and CI environments. - -```bash -$ bun install --frozen-lockfile -``` - -To perform a dry run (i.e. don't actually install anything): - -```bash -$ bun install --dry-run -``` +## Logging To modify logging verbosity: @@ -66,86 +44,59 @@ $ bun install --verbose # debug logging $ bun install --silent # no logging ``` -{% details summary="Configuring behavior" %} -The default behavior of `bun install` can be configured in `bunfig.toml`: - -```toml -[install] - -# whether to install optionalDependencies -optional = true +## Lifecycle scripts -# whether to install devDependencies -dev = true - -# whether to install peerDependencies -peer = false - -# equivalent to `--production` flag -production = false - -# equivalent to `--frozen-lockfile` flag -frozenLockfile = false - -# equivalent to `--dry-run` flag -dryRun = false -``` - -{% /details %} +Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts like `postinstall` for installed dependencies. Executing arbitrary scripts represents a potential security risk. -## `bun add` - -To add a particular package: - -```bash -$ bun add preact -``` - -To specify a version, version range, or tag: - -```bash -$ bun add zod@3.20.0 -$ bun add zod@^3.0.0 -$ bun add zod@latest -``` - -To add a package as a dev dependency (`"devDependencies"`): +To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json. -```bash -$ bun add --dev @types/react -$ bun add -d @types/react +```json-diff + { + "name": "my-app", + "version": "1.0.0", ++ "trustedDependencies": ["my-trusted-package"] + } ``` -To add a package as an optional dependency (`"optionalDependencies"`): +Then re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`. -```bash -$ bun add --optional lodash -``` +## Workspaces -To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range. +Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](/docs/install/workspaces). -```bash -$ bun add react --exact +```json#package.json +{ + "name": "my-app", + "version": "1.0.0", + "workspaces": ["packages/*"], + "dependencies": { + "preact": "^10.5.13" + } +} ``` -This will add the following to your `package.json`: +## Overrides and resolutions -```jsonc -{ - "dependencies": { - // without --exact - "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0 +Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](/docs/install/overrides) for complete documentation. - // with --exact - "react": "18.2.0" // this matches only 18.2.0 exactly +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } } -} ``` -To install a package globally: +## Global packages + +To install a package globally, use the `-g`/`--global` flag. Typically this is used for installing command-line tools. ```bash -$ bun add --global cowsay # or `bun add -g cowsay` +$ bun install --global cowsay # or `bun install -g cowsay` $ cowsay "Bun!" ______ < Bun! > @@ -157,159 +108,75 @@ $ cowsay "Bun!" || || ``` -{% details summary="Configuring global installation behavior" %} - -```toml -[install] -# where `bun install --global` installs packages -globalDir = "~/.bun/install/global" +## Production mode -# where globally-installed package bins are linked -globalBinDir = "~/.bun/bin" -``` - -{% /details %} -To view a complete list of options for a given command: +To install in production mode (i.e. without `devDependencies` or `optionalDependencies`): ```bash -$ bun add --help +$ bun install --production ``` -## `bun remove` - -To remove a dependency: +For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated. ```bash -$ bun remove preact -``` - -## `bun update` - -To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_: - -```sh -$ bun update +$ bun install --frozen-lockfile ``` -This will not edit your `package.json`. There's currently no command to force-update all dependencies to the latest version regardless version ranges. - -## `bun link` +For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](/docs/install/lockfile). -Use `bun link` in a local directory to register the current package as a "linkable" package. +## Dry run -```bash -$ cd /path/to/cool-pkg -$ cat package.json -{ - "name": "cool-pkg", - "version": "1.0.0" -} -$ bun link -bun link v1.x (7416672e) -Success! Registered "cool-pkg" - -To use cool-pkg in a project, run: - bun link cool-pkg - -Or add it in dependencies in your package.json file: - "cool-pkg": "link:cool-pkg" -``` - -This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory. +To perform a dry run (i.e. don't actually install anything): ```bash -$ cd /path/to/my-app -$ bun link cool-pkg -``` - -In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`: - -```json-diff - { - "name": "my-app", - "version": "1.0.0", - "dependencies": { -+ "cool-pkg": "link:cool-pkg" - } - } -``` - -## Trusted dependencies - -Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine. - -<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. --> - -To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json. - -<!-- ```json-diff - { - "name": "my-app", - "version": "1.0.0", -+ "trustedDependencies": { -+ "my-trusted-package": "*" -+ } - } -``` --> - -```json-diff - { - "name": "my-app", - "version": "1.0.0", -+ "trustedDependencies": ["my-trusted-package"] - } +$ bun install --dry-run ``` -Bun reads this field and will run lifecycle scripts for `my-trusted-package`. - -<!-- If you specify a version range, Bun will only execute lifecycle scripts if the resolved package version matches the range. --> -<!-- -```json -{ - "name": "my-app", - "version": "1.0.0", - "trustedDependencies": { - "my-trusted-package": "^1.0.0" - } -} -``` --> - -## Git dependencies +## Non-npm dependencies -To add a dependency from a git repository: +Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](/docs/cli/add). -```bash -$ bun install git@github.com:moment/moment.git -``` - -Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more. - -```json +```json#package.json { "dependencies": { "dayjs": "git+https://github.com/iamkun/dayjs.git", "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21", "moment": "git@github.com:moment/moment.git", - "zod": "github:colinhacks/zod" + "zod": "github:colinhacks/zod", + "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz" } } ``` -## Tarball dependencies +## Configuration -A package name can correspond to a publicly hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry. +The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below. -```json#package.json -{ - "dependencies": { - "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz" - } -} +```toml +[install] + +# whether to install optionalDependencies +optional = true + +# whether to install devDependencies +dev = true + +# whether to install peerDependencies +peer = false + +# equivalent to `--production` flag +production = false + +# equivalent to `--frozen-lockfile` flag +frozenLockfile = false + +# equivalent to `--dry-run` flag +dryRun = false ``` ## CI/CD -Looking to speed up your CI? Use the official `oven-sh/setup-bun` action to install `bun` in a GitHub Actions pipeline. +Looking to speed up your CI? Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline. ```yaml#.github/workflows/release.yml name: bun-types diff --git a/docs/cli/link.md b/docs/cli/link.md new file mode 100644 index 000000000..9adc73765 --- /dev/null +++ b/docs/cli/link.md @@ -0,0 +1,46 @@ +Use `bun link` in a local directory to register the current package as a "linkable" package. + +```bash +$ cd /path/to/cool-pkg +$ cat package.json +{ + "name": "cool-pkg", + "version": "1.0.0" +} +$ bun link +bun link v1.x (7416672e) +Success! Registered "cool-pkg" + +To use cool-pkg in a project, run: + bun link cool-pkg + +Or add it in dependencies in your package.json file: + "cool-pkg": "link:cool-pkg" +``` + +This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory. + +```bash +$ cd /path/to/my-app +$ bun link cool-pkg +``` + +In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`: + +```json-diff + { + "name": "my-app", + "version": "1.0.0", + "dependencies": { ++ "cool-pkg": "link:cool-pkg" + } + } +``` + +To _unregister_ a local package, navigate to the package's root directory and run `bun unlink`. + +```bash +$ cd /path/to/cool-pkg +$ bun unlink +bun unlink v1.x (7416672e) +``` diff --git a/docs/install/utilities.md b/docs/cli/pm.md index 689f177d8..689f177d8 100644 --- a/docs/install/utilities.md +++ b/docs/cli/pm.md diff --git a/docs/cli/remove.md b/docs/cli/remove.md new file mode 100644 index 000000000..8054711d3 --- /dev/null +++ b/docs/cli/remove.md @@ -0,0 +1,5 @@ +To remove a dependency: + +```bash +$ bun remove ts-node +``` diff --git a/docs/cli/update.md b/docs/cli/update.md new file mode 100644 index 000000000..dfda37f01 --- /dev/null +++ b/docs/cli/update.md @@ -0,0 +1,7 @@ +To update all dependencies to the latest version _that's compatible with the version range specified in your `package.json`_: + +```sh +$ bun update +``` + +This will not edit your `package.json`. There's currently no command to force-update all dependencies to the latest version regardless version ranges. |