diff options
Diffstat (limited to 'docs')
28 files changed, 977 insertions, 522 deletions
diff --git a/docs/api/binary-data.md b/docs/api/binary-data.md index a5fa40d9e..91b314b98 100644 --- a/docs/api/binary-data.md +++ b/docs/api/binary-data.md @@ -26,10 +26,10 @@ Below is a quick "cheat sheet" that doubles as a table of contents. Click an ite --- -<!-- - [`File`](#file) -- _Browser only_. A subclass of `Blob` that represents a file. Has a `name` and `lastModified` timestamp. There is experimental support in Node.js v20; Bun does not support `File` yet; most of its functionality is provided by `BunFile`. +- [`File`](#file) +- A subclass of `Blob` that represents a file. Has a `name` and `lastModified` timestamp. There is experimental support in Node.js v20. ---- --> +--- - [`BunFile`](#bunfile) - _Bun only_. A subclass of `Blob` that represents a lazily-loaded file on disk. Created with `Bun.file(path)`. diff --git a/docs/api/spawn.md b/docs/api/spawn.md index a85f9d08c..644f8cee3 100644 --- a/docs/api/spawn.md +++ b/docs/api/spawn.md @@ -183,6 +183,60 @@ const proc = Bun.spawn(["echo", "hello"]); proc.unref(); ``` +## Inter-process communication (IPC) + +Bun supports direct inter-process communication channel between two `bun` processes. To receive messages from a spawned Bun subprocess, specify an `ipc` handler. +{%callout%} +**Note** — This API is only compatible with other `bun` processes. Use `process.execPath` to get a path to the currently running `bun` executable. +{%/callout%} + +```ts#parent.ts +const child = Bun.spawn(["bun", "child.ts"], { + ipc(message) { + /** + * The message received from the sub process + **/ + }, +}); +``` + +The parent process can send messages to the subprocess using the `.send()` method on the returned `Subprocess` instance. A reference to the sending subprocess is also available as the second argument in the `ipc` handler. + +```ts#parent.ts +const childProc = Bun.spawn(["bun", "child.ts"], { + ipc(message, childProc) { + /** + * The message received from the sub process + **/ + childProc.send("Respond to child") + }, +}); + +childProc.send("I am your father"); // The parent can send messages to the child as well +``` + +Meanwhile the child process can send messages to its parent using with `process.send()` and receive messages with `process.on("message")`. This is the same API used for `child_process.fork()` in Node.js. + +```ts#child.ts +process.send("Hello from child as string"); +process.send({ message: "Hello from child as object" }); + +process.on("message", (message) => { + // print message from parent + console.log(message); +}); +``` + +All messages are serialized using the JSC `serialize` API, which allows for the same set of [transferrable types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) supported by `postMessage` and `structuredClone`, including strings, typed arrays, streams, and objects. + +```ts#child.ts +// send a string +process.send("Hello from child as string"); + +// send an object +process.send({ message: "Hello from child as object" }); +``` + ## Blocking API (`Bun.spawnSync()`) Bun provides a synchronous equivalent of `Bun.spawn` called `Bun.spawnSync`. This is a blocking API that supports the same inputs and parameters as `Bun.spawn`. It returns a `SyncSubprocess` object, which differs from `Subprocess` in a few ways. diff --git a/docs/bundler/index.md b/docs/bundler/index.md index 7bb04cc82..3069654b2 100644 --- a/docs/bundler/index.md +++ b/docs/bundler/index.md @@ -328,7 +328,7 @@ Depending on the target, Bun will apply different module resolution rules and op All bundles generated with `target: "bun"` are marked with a special `// @bun` pragma, which indicates to the Bun runtime that there's no need to re-transpile the file before execution. - If any entrypoints contains a Bun shebang (`#!/usr/bin/env bun`) the bundler will default to `target: "bun"` instead of `"browser`. + If any entrypoints contains a Bun shebang (`#!/usr/bin/env bun`) the bundler will default to `target: "bun"` instead of `"browser"`. --- 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. diff --git a/docs/dev/css.md b/docs/dev/css.md index a74f5d1ea..53ebc6c06 100644 --- a/docs/dev/css.md +++ b/docs/dev/css.md @@ -49,7 +49,7 @@ This is useful for preventing flash of unstyled content. ## With `bun bun` -Bun bundles `.css` files imported via `@import` into a single file. It doesn’t autoprefix or minify CSS today. Multiple `.css` files imported in one JavaScript file will _not_ be bundled into one file. You’ll have to import those from a `.css` file. +Bun bundles `.css` files imported via `@import` into a single file. It doesn’t auto-prefix or minify CSS today. Multiple `.css` files imported in one JavaScript file will _not_ be bundled into one file. You’ll have to import those from a `.css` file. This input: diff --git a/docs/guides/ecosystem/docker.md b/docs/guides/ecosystem/docker.md new file mode 100644 index 000000000..26a1eaccd --- /dev/null +++ b/docs/guides/ecosystem/docker.md @@ -0,0 +1,140 @@ +--- +name: Containerize a Bun application with Docker +--- + +{% callout %} +This guide assumes you already have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed. +{% /callout %} + +[Docker](https://www.docker.com) is a platform for packaging and running an application as a lightweight, portable _container_ that encapsulates all the necessary dependencies. + +--- + +To _containerize_ our application, we define a `Dockerfile`. This file contains a list of instructions to initialize the container, copy our local project files into it, install dependencies, and starts the application. + +```docker#Dockerfile +# use the official Bun image +# see all versions at https://hub.docker.com/r/oven/bun/tags +FROM oven/bun:1 as base +WORKDIR /usr/src/app + +# install dependencies into temp directory +# this will cache them and speed up future builds +FROM base AS install +RUN mkdir -p /temp/dev +COPY package.json bun.lockb /temp/dev/ +RUN cd /temp/dev && bun install --frozen-lockfile + +# install with --production (exclude devDependencies) +RUN mkdir -p /temp/prod +COPY package.json bun.lockb /temp/prod/ +RUN cd /temp/prod && bun install --frozen-lockfile --production + +# copy node_modules from temp directory +# then copy all (non-ignored) project files into the image +FROM install AS prerelease +COPY --from=install /temp/dev/node_modules node_modules +COPY . . + +# [optional] tests & build +ENV NODE_ENV=production +RUN bun test +RUN bun run build + +# copy production dependencies and source code into final image +FROM base AS release +COPY --from=install /temp/prod/node_modules node_modules +COPY --from=prerelease /usr/src/app/index.ts . +COPY --from=prerelease /usr/src/app/package.json . + +# run the app +USER bun +EXPOSE 3000/tcp +ENTRYPOINT [ "bun", "run", "index.ts" ] +``` + +--- + +Now that you have your docker image, let's look at `.dockerignore` which has the same syntax as `.gitignore`, here you need to specify the files/directories that must not go in any stage of the docker build. An example for a ignore file is + +```txt#.dockerignore +node_modules +Dockerfile* +docker-compose* +.dockerignore +.git +.gitignore +README.md +LICENSE +.vscode +Makefile +helm-charts +.env +.editorconfig +.idea +coverage* +``` + +--- + +We'll now use `docker build` to convert this `Dockerfile` into a _Docker image_, is a self-contained template containing all the dependencies and configuration required to run the application. + +The `-t` flag lets us specify a name for the image, and `--pull` tells Docker to automatically download the latest version of the base image (`oven/bun`). The initial build will take longer, as Docker will download all the base images and dependencies. + +```bash +$ docker build --pull -t bun-hello-world . +[+] Building 0.9s (21/21) FINISHED + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 37B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 35B 0.0s + => [internal] load metadata for docker.io/oven/bun:1 0.8s + => [auth] oven/bun:pull token for registry-1.docker.io 0.0s + => [base 1/2] FROM docker.io/oven/bun:1@sha256:373265748d3cd3624cb3f3ee6004f45b1fc3edbd07a622aeeec17566d2756997 0.0s + => [internal] load build context 0.0s + => => transferring context: 155B 0.0s + # ...lots of commands... + => exporting to image 0.0s + => => exporting layers 0.0s + => => writing image sha256:360663f7fdcd6f11e8e94761d5592e2e4dfc8d167f034f15cd5a863d5dc093c4 0.0s + => => naming to docker.io/library/bun-hello-world 0.0s +``` + +--- + +We've built a new _Docker image_. Now let's use that image to spin up an actual, running _container_. + +We'll use `docker run` to start a new container using the `bun-hello-world` image. It will be run in _detached_ mode (`-d`) and we'll map the container's port 3000 to our local machine's port 3000 (`-p 3000:3000`). + +The `run` command prints a string representing the _container ID_. + +```sh +$ docker run -d -p 3000:3000 bun-hello-world +7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d +``` + +--- + +The container is now running in the background. Visit [localhost:3000](http://localhost:3000). You should see a `Hello, World!` message. + +--- + +To stop the container, we'll use `docker stop <container-id>`. + +```sh +$ docker stop 7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d +``` + +--- + +If you can't find the container ID, you can use `docker ps` to list all running containers. + +```sh +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +7f03e212a15e bun-hello-world "bun run index.ts" 2 minutes ago Up 2 minutes 0.0.0.0:3000->3000/tcp flamboyant_cerf +``` + +--- + +That's it! Refer to the [Docker documentation](https://docs.docker.com/) for more advanced usage. diff --git a/docs/guides/ecosystem/pm2.md b/docs/guides/ecosystem/pm2.md new file mode 100644 index 000000000..c775c8ca3 --- /dev/null +++ b/docs/guides/ecosystem/pm2.md @@ -0,0 +1,54 @@ +--- +name: Run Bun as a daemon with PM2 +--- + +[PM2](https://pm2.keymetrics.io/) is a popular process manager that manages and runs your applications as daemons (background processes). + +It offers features like process monitoring, automatic restarts, and easy scaling. Using a process manager is common when deploying a Bun application on a cloud-hosted virtual private server (VPS), as it: + +- Keeps your Node.js application running continuously. +- Ensure high availability and reliability of your application. +- Monitor and manage multiple processes with ease. +- Simplify the deployment process. + +--- + +You can use PM2 with Bun in two ways: as a CLI option or in a configuration file. + +### With `--interpreter` + +--- + +To start your application with PM2 and Bun as the interpreter, open your terminal and run the following command: + +```bash +pm2 start --interpreter ~/.bun/bin/bun index.ts +``` + +--- + +### With a configuration file + +--- + +Alternatively, you can create a PM2 configuration file. Create a file named `pm2.config.js` in your project directory and add the following content. + +```javascript +module.exports = { + name: "app", // Name of your application + script: "index.ts", // Entry point of your application + interpreter: "~/.bun/bin/bun", // Path to the Bun interpreter +}; +``` + +--- + +After saving the file, you can start your application with PM2 + +```bash +pm2 start pm2.config.js +``` + +--- + +That’s it! Your JavaScript/TypeScript web server is now running as a daemon with PM2 using Bun as the interpreter. diff --git a/docs/guides/ecosystem/systemd.md b/docs/guides/ecosystem/systemd.md new file mode 100644 index 000000000..c22fc9ae2 --- /dev/null +++ b/docs/guides/ecosystem/systemd.md @@ -0,0 +1,113 @@ +--- +name: Run Bun as a daemon with systemd +--- + +[systemd](https://systemd.io) is an init system and service manager for Linux operating systems that manages the startup and control of system processes and services. + +<!-- systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and auto mount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit. --> + +<!-- Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution. --> + +--- + +To run a Bun application as a daemon using **systemd** you'll need to create a _service file_ in `/lib/systemd/system/`. + +```sh +$ cd /lib/systemd/system +$ touch my-app.service +``` + +--- + +Here is a typical service file that runs an application on system start. You can use this as a template for your own service. Replace `YOUR_USER` with the name of the user you want to run the application as. To run as `root`, replace `YOUR_USER` with `root`, though this is generally not recommended for security reasons. + +Refer to the [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html) for more information on each setting. + +```ini#my-app.service +[Unit] +# describe the app +Description=My App +# start the app after the network is available +After=network.target + +[Service] +# usually you'll use 'simple' +# one of https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type= +Type=simple +# which user to use when starting the app +User=YOUR_USER +# path to your application's root directory +WorkingDirectory=/home/YOUR_USER/path/to/my-app +# the command to start the app +# requires absolute paths +ExecStart=/home/YOUR_USER/.bun/bin/bun run index.ts +# restart policy +# one of {no|on-success|on-failure|on-abnormal|on-watchdog|on-abort|always} +Restart=always + +[Install] +# start the app automatically +WantedBy=multi-user.target +``` + +--- + +If your application starts a webserver, note that non-`root` users are not able to listen on ports 80 or 443 by default. To permanently allow Bun to listen on these ports when executed by a non-`root` user, use the following command. This step isn't necessary when running as `root`. + +```bash +$ sudo setcap CAP_NET_BIND_SERVICE=+eip ~/.bun/bin/bun +``` + +--- + +With the service file configured, you can now _enable_ the service. Once enabled, it will start automatically on reboot. This requires `sudo` permissions. + +```bash +$ sudo systemctl enable my-app +``` + +--- + +To start the service without rebooting, you can manually _start_ it. + +```bash +$ sudo systemctl start my-app +``` + +--- + +Check the status of your application with `systemctl status`. If you've started your app successfully, you should see something like this: + +```bash +$ sudo systemctl status my-app +● my-app.service - My App + Loaded: loaded (/lib/systemd/system/my-app.service; enabled; preset: enabled) + Active: active (running) since Thu 2023-10-12 11:34:08 UTC; 1h 8min ago + Main PID: 309641 (bun) + Tasks: 3 (limit: 503) + Memory: 40.9M + CPU: 1.093s + CGroup: /system.slice/my-app.service + └─309641 /home/YOUR_USER/.bun/bin/bun run /home/YOUR_USER/application/index.ts +``` + +--- + +To update the service, edit the contents of the service file, then reload the daemon. + +```bash +$ sudo systemctl daemon-reload +``` + +--- + +For a complete guide on the service unit configuration, you can check [this page](https://www.freedesktop.org/software/systemd/man/systemd.service.html). Or refer to this cheatsheet of common commands: + +```bash +$ sudo systemctl daemon-reload # tell systemd that some files got changed +$ sudo systemctl enable my-app # enable the app (to allow auto-start) +$ sudo systemctl disable my-app # disable the app (turns off auto-start) +$ sudo systemctl start my-app # start the app if is stopped +$ sudo systemctl stop my-app # stop the app +$ sudo systemctl restart my-app # restart the app +``` diff --git a/docs/guides/ecosystem/vite.md b/docs/guides/ecosystem/vite.md index 03ff85472..cf77e7249 100644 --- a/docs/guides/ecosystem/vite.md +++ b/docs/guides/ecosystem/vite.md @@ -30,8 +30,7 @@ bun install Start the development server with the `vite` CLI using `bunx`. -The `--bun` flag tells Bun to run Vite's CLI using `bun` instead of `node`; by default Bun respects Vite's `#!/usr/bin/env node` [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). After Bun 1.0 this flag will no longer be necessary. - +The `--bun` flag tells Bun to run Vite's CLI using `bun` instead of `node`; by default Bun respects Vite's `#!/usr/bin/env node` [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). ```bash bunx --bun vite ``` diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md index d0d841eea..0c1ac6362 100644 --- a/docs/guides/install/trusted.md +++ b/docs/guides/install/trusted.md @@ -47,4 +47,4 @@ Note that this only allows lifecycle scripts for the specific package listed in --- -See [Docs > Package manager > Trusted dependencies](/docs/cli/install#trusted-dependencies) for complete documentation of trusted dependencies. +See [Docs > Package manager > Trusted dependencies](/docs/install/lifecycle) for complete documentation of trusted dependencies. diff --git a/docs/guides/process/ipc.md b/docs/guides/process/ipc.md new file mode 100644 index 000000000..af029a524 --- /dev/null +++ b/docs/guides/process/ipc.md @@ -0,0 +1,66 @@ +--- +name: Spawn a child process and communicate using IPC +--- + +Use [`Bun.spawn()`](/docs/api/spawn) to spawn a child process. When spawning a second `bun` process, you can open a direct inter-process communication (IPC) channel between the two processes. + +{%callout%} +**Note** — This API is only compatible with other `bun` processes. Use `process.execPath` to get a path to the currently running `bun` executable. +{%/callout%} + +```ts#parent.ts +const child = Bun.spawn(["bun", "child.ts"], { + ipc(message) { + /** + * The message received from the sub process + **/ + }, +}); +``` + +--- + +The parent process can send messages to the subprocess using the `.send()` method on the returned `Subprocess` instance. A reference to the sending subprocess is also available as the second argument in the `ipc` handler. + +```ts#parent.ts +const childProc = Bun.spawn(["bun", "child.ts"], { + ipc(message, childProc) { + /** + * The message received from the sub process + **/ + childProc.send("Respond to child") + }, +}); + +childProc.send("I am your father"); // The parent can send messages to the child as well +``` + +--- + +Meanwhile the child process can send messages to its parent using with `process.send()` and receive messages with `process.on("message")`. This is the same API used for `child_process.fork()` in Node.js. + +```ts#child.ts +process.send("Hello from child as string"); +process.send({ message: "Hello from child as object" }); + +process.on("message", (message) => { + // print message from parent + console.log(message); +}); +``` + +--- + +All messages are serialized using the JSC `serialize` API, which allows for the same set of [transferrable types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) supported by `postMessage` and `structuredClone`, including strings, typed arrays, streams, and objects. + +```ts#child.ts +// send a string +process.send("Hello from child as string"); + +// send an object +process.send({ message: "Hello from child as object" }); +``` + +--- + +See [Docs > API > Child processes](/docs/api/spawn) for complete documentation. diff --git a/docs/index.md b/docs/index.md index 0cc294150..3fbb7576d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. --> diff --git a/docs/install/lifecycle.md b/docs/install/lifecycle.md new file mode 100644 index 000000000..035ead24d --- /dev/null +++ b/docs/install/lifecycle.md @@ -0,0 +1,44 @@ +Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some of the most common are below, but there are [many others](https://docs.npmjs.com/cli/v10/using-npm/scripts). + +- `preinstall`: Runs before the package is installed +- `postinstall`: Runs after the package is installed +- `preuninstall`: Runs before the package is uninstalled +- `prepublishOnly`: Runs before the package is published + +These scripts are arbitrary shell commands that the package manager is expected to read and execute at the appropriate time. But executing arbitrary scripts represents a potential security risk, so—unlike other `npm` clients—Bun does not execute arbitrary lifecycle scripts by default. + +## `postinstall` + +The `postinstall` script is particularly important. It's widely used to build or install platform-specific binaries for packages that are implemented as [native Node.js add-ons](https://nodejs.org/api/addons.html). For example, `node-sass` is a popular package that uses `postinstall` to build a native binary for Sass. + +```json +{ + "name": "my-app", + "version": "1.0.0", + "dependencies": { + "node-sass": "^6.0.1" + } +} +``` + +## `trustedDependencies` + +Instead of executing arbitrary scripts, Bun uses a "default-secure" approach. You can add certain packages to an allow list, and Bun will execute lifecycle scripts for those packages. To tell Bun to allow lifecycle scripts for a particular package, add the package name to `trustedDependencies` array in your `package.json`. + +```json-diff + { + "name": "my-app", + "version": "1.0.0", ++ "trustedDependencies": ["node-sass"] + } +``` + +Once added to `trustedDependencies`, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`. + +## `--ignore-scripts` + +To disable lifecycle scripts for all packages, use the `--no-scripts` flag. + +```bash +$ bun install --no-scripts +``` diff --git a/docs/install/overrides.md b/docs/install/overrides.md new file mode 100644 index 000000000..f226c35bd --- /dev/null +++ b/docs/install/overrides.md @@ -0,0 +1,73 @@ +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. + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } + } +``` + +By default, Bun will install the latest version of all dependencies and metadependencies, according to the ranges specified in each package's `package.json`. Let's say you have a project with one dependency, `foo`, which in turn has a dependency on `bar`. This means `bar` is a _metadependency_ of our project. + +```json#package.json +{ + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + } +} +``` + +When you run `bun install`, Bun will install the latest versions of each package. + +``` +# tree layout of node_modules +node_modules +├── foo@1.2.3 +└── bar@4.5.6 +``` + +But what if a security vulnerability was introduced in `bar@4.5.6`? We may want a way to pin `bar` to an older version that doesn't have the vulerability. This is where `"overrides"`/`"resolutions"` come in. + +## `"overrides"` + +Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the specified version range when determining which version of `bar` to install, whether it's a dependency or a metadependency. + +{% callout %} +**Note** — Bun currently only supports top-level `"overrides"`. [Nested overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported. +{% /callout %} + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "overrides": { ++ "bar": "~4.4.0" ++ } + } +``` + +## `"resolutions"` + +The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier. + +As with `"overrides"`, _nested resolutions_ are not currently supported. + +```json-diff#package.json + { + "name": "my-app", + "dependencies": { + "foo": "^2.0.0" + }, ++ "resolutions": { ++ "bar": "~4.4.0" ++ } + } +``` diff --git a/docs/installation.md b/docs/installation.md index 73d222eaf..6aa51737a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,9 +1,12 @@ Bun ships as a single executable that can be installed a few different ways. -## macOS and Linux +## Installing + +### macOS and Linux {% callout %} -**Linux users** — The `unzip` package is required to install Bun. Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. +**Linux users** — The `unzip` package is required to install Bun. Use `sudo apt install unzip` to install `unzip` package. +Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Use `uname -r` to check Kernel version. {% /callout %} {% codetabs %} @@ -34,7 +37,7 @@ $ proto install bun {% /codetabs %} -## Windows +### Windows Bun provides a _limited, experimental_ native build for Windows. At the moment, only the Bun runtime is supported. @@ -66,6 +69,59 @@ $ docker pull oven/bun:alpine $ docker pull oven/bun:distroless ``` +## Checking installation + +To check that Bun was installed successfully, open a new terminal window and 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 +``` + +If you've installed Bun but are seeing a `command not found` error, you may have to manually add the installation directory (`~/.bun/bin`) to your `PATH`. + +{% details summary="How to add to your `PATH`" %} +First, determine what shell you're using: + +```sh +$ echo $SHELL +/bin/zsh # or /bin/bash or /bin/fish +``` + +Then add these lines below to bottom of your shell's configuration file. + +{% codetabs %} + +```bash#~/.zshrc +# add to ~/.zshrc +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +```bash#~/.bashrc +# add to ~/.bashrc +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +```sh#~/.config/fish/config.fish +# add to ~/.config/fish/config.fish +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" +``` + +{% /codetabs %} +Save the file. You'll need to open a new shell/terminal window for the changes to take effect. + +{% /details %} + ## Upgrading Once installed, the binary can upgrade itself. diff --git a/docs/nav.ts b/docs/nav.ts index 2f9d74024..ccf3679fe 100644 --- a/docs/nav.ts +++ b/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("Templating"), + 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.", @@ -152,6 +152,21 @@ export default { description: "Install all dependencies with `bun install`, or manage dependencies with `bun add` and `bun remove`.", }), + page("cli/add", "`bun add`", { + description: "Add dependencies to your project.", + }), + page("cli/remove", "`bun remove`", { + description: "Remove dependencies from your project.", + }), + page("cli/update", "`bun update`", { + description: "Update your project's dependencies.", + }), + page("cli/link", "`bun link`", { + description: "Install local packages as dependencies in your project.", + }), + page("cli/pm", "`bun pm`", { + description: "Utilities relating to package management with Bun.", + }), page("install/cache", "Global cache", { description: "Bun's package manager installs all packages into a shared global cache to avoid redundant re-downloads.", @@ -159,6 +174,9 @@ export default { page("install/workspaces", "Workspaces", { description: "Bun's package manager supports workspaces and mono-repo development workflows.", }), + page("install/lifecycle", "Lifecycle scripts", { + description: "How Bun handles package lifecycle scripts with trustedDependencies", + }), page("install/lockfile", "Lockfile", { description: "Bun's binary lockfile `bun.lockb` tracks your resolved dependency tree, making future installs fast and repeatable.", @@ -166,9 +184,12 @@ export default { page("install/registries", "Scopes and registries", { description: "How to configure private scopes and custom package registries.", }), - page("install/utilities", "Utilities", { - description: "Use `bun pm` to introspect your global module cache or project dependency tree.", + page("install/overrides", "Overrides and resolutions", { + description: "Specify version ranges for nested dependencies", }), + // page("install/utilities", "Utilities", { + // description: "Use `bun pm` to introspect your global module cache or project dependency tree.", + // }), divider("Bundler"), page("bundler", "`Bun.build`", { diff --git a/docs/project/development.md b/docs/project/development.md index 6963df434..4e0ae7825 100644 --- a/docs/project/development.md +++ b/docs/project/development.md @@ -49,6 +49,12 @@ $ wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 16 all $ sudo pacman -S llvm clang lld ``` +```bash#Fedora +$ sudo dnf install 'dnf-command(copr)' +$ sudo dnf copr enable -y @fedora-llvm-team/llvm-snapshots +$ sudo dnf install llvm clang lld +``` + {% /codetabs %} If none of the above solutions apply, you will have to install it [manually](https://github.com/llvm/llvm-project/releases/tag/llvmorg-16.0.6). @@ -98,6 +104,10 @@ $ sudo apt install cargo ccache cmake git golang libtool ninja-build pkg-config $ sudo pacman -S base-devel ccache cmake esbuild git go libiconv libtool make ninja pkg-config python rust sed unzip ``` +```bash#Fedora +$ sudo dnf install cargo ccache cmake git golang libtool ninja-build pkg-config rustc golang-github-evanw-esbuild libatomic-static libstdc++-static sed unzip +``` + {% /codetabs %} {% details summary="Ubuntu — Unable to locate package esbuild" %} @@ -120,11 +130,11 @@ Zig can be installed either with our npm package [`@oven/zig`](https://www.npmjs ```bash $ bun install -g @oven/zig -$ zigup 0.12.0-dev.163+6780a6bbf +$ zigup 0.12.0-dev.888+130227491 ``` {% callout %} -We last updated Zig on **July 18th, 2023** +We last updated Zig on **October 12th, 2023** {% /callout %} ## First Build diff --git a/docs/runtime/bunfig.md b/docs/runtime/bunfig.md index 83f66b1b1..6950d8233 100644 --- a/docs/runtime/bunfig.md +++ b/docs/runtime/bunfig.md @@ -209,7 +209,7 @@ dev = true ### `install.peer` -Whether to install peer dependencies. Default `false`. +Whether to install peer dependencies. Default `true`. ```toml [install] diff --git a/docs/runtime/nodejs-apis.md b/docs/runtime/nodejs-apis.md index f128e0cd2..4b58343e0 100644 --- a/docs/runtime/nodejs-apis.md +++ b/docs/runtime/nodejs-apis.md @@ -30,7 +30,7 @@ This page is updated regularly to reflect compatibility status of the latest ver ### [`node:crypto`](https://nodejs.org/api/crypto.html) -🟡 Missing `Certificate` `ECDH` `KeyObject` `X509Certificate` `checkPrime` `checkPrimeSync` `createPrivateKey` `createPublicKey` `createSecretKey` `diffieHellman` `generateKey` `generateKeyPair` `generateKeyPairSync` `generateKeySync` `generatePrime` `generatePrimeSync` `getCipherInfo` `getFips` `hkdf` `hkdfSync` `secureHeapUsed` `setEngine` `setFips` `sign` `verify` +🟡 Missing `Certificate` `ECDH` `X509Certificate` `checkPrime` `checkPrimeSync` `diffieHellman` `generatePrime` `generatePrimeSync` `getCipherInfo` `getFips` `hkdf` `hkdfSync` `secureHeapUsed` `setEngine` `setFips` Some methods are not optimized yet. |