bun upgrade --canary command
Run `bun upgrade --canary` to upgrade to the latest canary release, which includes changes and bug fixes that haven't reached a stable release yet.
package manager commands
101 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
bun upgrade command
Run `bun upgrade` to upgrade Bun to the latest stable version. This is the recommended first step when troubleshooting issues.
bun feedback command with email flag
The `bun feedback` command accepts an optional `--email` flag to specify an email address when sending feedback: `bun feedback --email you@example.com`.
bun install for production deployment
When deploying a Bun application in production via Docker, use `bun install --production --frozen-lockfile` to install only production dependencies and ensure reproducible builds. The frozen-lockfile flag prevents modifications to the lock file during installation.
Create Astro app with Bun
To initialize a fresh Astro app with Bun, run `bun create astro`. The create-astro package detects when you are using bunx and installs dependencies with bun.
bun install --frozen-lockfile option
The --frozen-lockfile option for bun install installs dependencies without modifying the lockfile, ensuring reproducible builds in Docker containers.
bun install --production option
The --production option for bun install excludes devDependencies from installation, used in Docker to create a minimal production image.
Install Express with Bun
To install Express in a Bun project, run: bun add express
Create a new Hono project with Bun
Use the command 'bun create hono myapp' to scaffold a new Hono project. When prompted for a template, select 'bun'. This clones the honojs/starter repository and copies the project files.
Install dependencies for a Hono Bun project
Navigate into the created Hono project directory and run 'bun install' to install all project dependencies.
Start dev server for Hono with Bun
Run 'bun run dev' to start the development server for a Hono project. The server runs on localhost:3000 by default.
Install Prisma with Bun
Install Prisma CLI as a dev dependency with `bun add -d prisma`, and install Prisma Client with `@prisma/client` along with the accelerate extension using `bun add @prisma/client @prisma/extension-accelerate`.
Install React for SSR
To set up React for server-side rendering, use 'bun add react react-dom' to install both packages.
bun add --dev adds to devDependencies
When using `bun add --dev`, the package is added to the `devDependencies` section in `package.json` rather than the regular `dependencies` section.
bun add --dev command syntax
To add an npm package as a development dependency, use the command `bun add --dev` or the shorthand `bun add -d` followed by the package name. For example: `bun add zod --dev` or `bun add zod -d`.
bun add with github: protocol
The command `bun add github:owner/repo` adds a GitHub repository as a dependency. For example, `bun add github:lodash/lodash` adds lodash to the project and writes `"lodash": "github:lodash/lodash"` to package.json dependencies.
Git dependency protocols supported
Bun supports multiple protocols for specifying Git dependencies: `github:owner/repo`, `git+https://github.com/owner/repo.git`, `git+ssh://github.com/owner/repo.git`, and `git@github.com:owner/repo.git`. Git protocols can optionally include a ref (branch, tag, or commit hash) after a `#` character, for example `git+ssh://github.com/lodash/lodash.git#4.17.21`.
GitHub dependencies downloaded as HTTP tarballs
When possible, Bun downloads GitHub dependencies as HTTP tarballs, which is faster than other methods.
Example: adding optional dependency with bun add
The command `bun add zod --optional` adds the zod package as an optional dependency, which results in it being added to the `optionalDependencies` field in package.json as `"zod": "^3.0.0"`.
bun add --optional flag
Use the `--optional` flag with `bun add` to add a package as an optional dependency. This adds the package to the `optionalDependencies` field in package.json instead of regular dependencies.
bun install installs peer dependencies by default
The `bun install` command installs peer dependencies by default, unless they are marked as optional in the peerDependenciesMeta field of package.json. Peer dependencies can be marked as optional by setting `peerDependenciesMeta[packageName].optional` to true.
Add peer dependency with --peer flag
To add an npm package as a peer dependency, use the `bun add` command with the `--peer` flag. For example, `bun add @types/bun --peer` adds the @types/bun package to peerDependencies in package.json.
Mark peer dependency as optional
To mark a peer dependency as optional, add an entry in the peerDependenciesMeta object with the package name as the key and set the optional field to true. For example, marking @types/bun as optional adds `"peerDependenciesMeta": { "@types/bun": { "optional": true } }` to package.json.
bun add with tarball URL
Bun's package manager can install any publicly available tarball URL as a dependency. Use the command `bun add package-name@<URL>` where the URL points to a tarball file. For example: `bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz`. The command downloads, extracts, and installs the tarball into the project's `node_modules` directory, and adds an entry to `package.json` with the package name as the key and the full URL as the value.
Tarball dependency in package.json format
When a tarball URL is added as a dependency via `bun add`, the `package.json` entry uses the full tarball URL as the version value. Example: `"zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"`.
bun add default range specifier is caret (^)
By default, Bun uses the `^` range specifier when adding packages. The caret range accepts future minor and patch versions. For example, `bun add zod` adds `"zod": "^3.0.0"` to `package.json`.
bun add command adds npm package as dependency
Use `bun add <package-name>` to add an npm package as a dependency. The package is added to the `dependencies` field in `package.json`.
bun add --exact pins to exact installed version
Use `bun add <package-name> --exact` to pin the package to the exact version without the caret range specifier. This adds the package to `dependencies` with an exact version number, e.g., `"zod": "3.0.0"`.
bun add accepts version specifiers and tags
You can specify an exact version or a tag when adding a package. Use `bun add zod@3.0.0` for a specific version, or `bun add zod@next` for a specific tag.
Default npm registry for bun install
The default npm registry used by bun install is registry.npmjs.org.
Environment variables in registry configuration
The registry configuration in bunfig.toml can reference environment variables using the syntax $variable_name. Bun automatically loads environment variables from .env.local, .env.[NODE_ENV], and .env files. For example: registry = { url = "https://registry.npmjs.org", token = "$npm_token" }.
Override npm registry in bunfig.toml
Override the default npm registry globally by setting the registry option in the [install] section of bunfig.toml. The registry can be configured as a string: registry = "https://registry.npmjs.org". The registry can also be configured as a table with url and token: registry = { url = "https://registry.npmjs.org", token = "123456" }. Alternatively, provide credentials in the URL itself: registry = "https://usertitle:password@registry.npmjs.org".
Configure git to diff Bun binary lockfile .lockb
To teach git how to generate a human-readable diff of Bun's binary lockfile format `.lockb`, add `*.lockb binary diff=lockb` to your local or global `.gitattributes` file. Then configure git with: `git config diff.lockb.textconv bun` and `git config diff.lockb.binary true`. For global configuration, use `git config --global` instead.
How git diff for bun.lockb works
The `textconv` configuration tells git to run bun on the file before diffing. The `binary` configuration tells git to treat the file as binary so it does not try to diff it line-by-line. Running Bun on the lockfile with `bun ./bun.lockb` prints a human-readable version of it, which `git diff` then diffs.
bun i -g installs packages globally
bun i -g <package> installs a package globally. By default, globally-installed packages go into a .bun/install/global/node_modules folder inside the home directory. Globally-installed packages can be run without the bun run prefix.
bun install replaces npm install
bun install is a fast, Node.js-compatible npm client. Run bun install instead of npm install to migrate from npm. It installs a Node.js compatible node_modules folder that works for Node.js projects without any code changes and without using Bun's runtime.
bun install converts package-lock.json to bun.lock
bun install automatically converts package-lock.json to Bun's bun.lock lockfile format while preserving existing resolved dependency versions.
bun install reads .npmrc configuration
bun install is compatible with .npmrc and reads npm registry configuration from it, allowing the same configuration to be used for both npm and Bun.
bun install uses hardlinks on Windows and Linux
On Windows and Linux, bun install uses hardlinks to save disk space and speed up installs.
bun install command shortcuts
bun i is equivalent to bun install. bun i -d adds devDependencies. bun rm removes a dependency.
bun run scripts replaces npm run, npx, and node
bun <script> runs scripts from package.json. bun <bin> runs executables from node_modules/.bin. bun <file> runs JavaScript/TypeScript files. bunx <package> runs packages like npx. bun run <executable> uses the locally-installed executable.
bun install supports workspaces
bun install supports workspaces similarly to npm. In package.json, set workspaces to an array of relative paths, such as ["packages/*", "apps/*"].
bun --filter runs commands across workspaces
The --filter flag accepts a glob pattern and runs the command concurrently for every workspace package whose name matches it, respecting dependency order. For example, bun --filter 'lib-*' my-script runs my-script for all packages whose name matches the glob.
bun update command syntax
bun update <package> updates a dependency to the latest version that satisfies the semver range in package.json. bun update without arguments updates all dependencies. bun update --latest ignores semver and updates to the latest version. bun update <package>@<version> updates to a specific version. bun update --latest updates all dependencies to the latest versions.
bun outdated command
bun outdated lists outdated dependencies with more compact output than npm outdated. It shows columns for Package, Current version, Update version (respecting semver), and Latest version.
bun pm ls lists installed packages
bun pm ls lists packages installed in the node_modules folder using Bun's lockfile as the source of truth. It lists only top-level packages by default. bun pm ls -a also lists transitive dependencies.
bun pm pack creates a package tarball
bun pm pack creates a tarball of the package in the current directory. The output shows total files, shasum, integrity hash, unpacked size, and packed size.
bun run respects node shebang by default
If a package references node in the #!/usr/bin/env node shebang, bun run respects it by default and uses the system's node executable. To force it to use Bun instead, pass --bun to bun run. When --bun is passed, Bun creates a symlink to the locally-installed Bun executable named 'node' in a temporary directory and adds it to PATH for the duration of the script.
bun add package under alias syntax
To install an npm package under a different name, use the command: bun add my-custom-name@npm:zod. This installs the 'zod' package but names it 'my-custom-name' in package.json and makes it importable by the alias name.
Import aliased package example
After installing a package with an alias using bun add my-custom-name@npm:zod, you can import it by its alias name: import { z } from "my-custom-name";
Configure scoped registry with username and password in bunfig.toml
A scoped registry in [install.scopes] can be specified as an object with username, password, and url fields. Environment variables can be referenced using the dollar sign prefix, for example: "@myorg2" = { username = "myusername", password = "$npm_pass", url = "https://registry.myorg.com/" }
Configure scoped registry with token in bunfig.toml
A scoped registry in [install.scopes] can be specified as an object with token and url fields. Environment variables can be referenced using the dollar sign prefix, for example: "@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
Configure scoped registry in bunfig.toml with string URL
To configure a private registry for an npm scope in bunfig.toml, use the [install.scopes] section. A scoped registry can be specified as a string containing the registry URL with embedded credentials. For example: "@myorg1" = "https://usertitle:password@registry.myorg.com/"
Scoped registries can be configured in .npmrc or bunfig.toml
Private registries for npm scopes can be configured in either .npmrc or bunfig.toml. The recommendation is to use bunfig.toml for its Bun-specific options.
bunfig.toml environment variable substitution
The bunfig.toml configuration file can reference environment variables. Bun automatically loads environment variables from .env.local, .env.[NODE_ENV], and .env files.
Example trustedDependencies configuration
To add a trusted dependency, include it in the package.json like this: ```json { "name": "my-app", "version": "1.0.0", "trustedDependencies": ["my-trusted-package"] } ```
Bun does not execute lifecycle scripts by default
Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as postinstall and node-gyp builds. These scripts represent a potential security risk because they can execute arbitrary code on your machine.
Default allowlist of trusted dependencies
Bun includes a default allowlist of popular packages whose postinstall scripts are known to be safe. This allowlist is defined in src/install/default-trusted-dependencies.txt in the Bun repository. It only applies to packages installed from npm. For packages from other sources such as file:, link:, git:, or github: dependencies, you must explicitly add them to trustedDependencies.
Errors when lifecycle scripts are needed
If you see the errors 'error: could not determine executable to run for package' or 'InvalidExe', you are probably using a package that needs its postinstall script to work.
bun pm trust command
To allow Bun to execute lifecycle scripts for a specific package, run bun pm trust <pkg>. This command automatically adds the package to trustedDependencies in your package.json.