From 011e157cac7698050370e24495a9002dacfceea9 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 13 Apr 2023 18:26:45 -0700 Subject: [PATCH] Docs restructuring (#2638) * Restructure * Update nav * Reorg * Reshuffle ecosystem pages * Split up runtime/runtime * Back to runtime/index * Fix issue * Split up runtime/index * Add Writing Tests page * Prettier matcher table * More updates --- docs/api/ffi.md | 21 +- docs/api/file-io.md | 6 +- docs/api/globals.md | 6 +- docs/api/http.md | 6 +- docs/api/spawn.md | 21 +- docs/api/tcp.md | 6 +- docs/api/utils.md | 8 +- docs/api/websockets.md | 4 +- docs/cli/bunx.md | 10 +- docs/cli/create.md | 26 ++ docs/cli/install.md | 296 +++------------ docs/cli/run.md | 59 ++- docs/cli/test.md | 221 ++--------- docs/ecosystem/express.md | 6 +- docs/ecosystem/react.md | 8 +- docs/index.md | 2 +- docs/install/cache.md | 59 +++ docs/install/index.md | 190 ++++++++++ docs/install/lockfile.md | 67 ++++ docs/install/registries.md | 26 ++ docs/install/utilities.md | 58 +++ docs/install/workspaces.md | 30 ++ docs/installation.md | 2 +- docs/nav.ts | 161 +++++--- docs/project/benchmarking.md | 15 +- docs/runtime/autoimport.md | 98 +++++ docs/runtime/bun-apis.md | 75 ++++ docs/{project => runtime}/configuration.md | 24 +- docs/runtime/index.md | 44 ++- docs/runtime/jsx.md | 35 ++ docs/runtime/loaders.md | 81 +++- docs/runtime/modules.md | 101 ----- .../nodejs.md => runtime/nodejs-apis.md} | 3 +- docs/runtime/plugins.md | 4 +- docs/{ecosystem => runtime}/typescript.md | 23 +- docs/runtime/web-apis.md | 266 ++----------- docs/templates.md | 256 +++++++++++++ docs/test/writing.md | 357 ++++++++++++++++++ 38 files changed, 1750 insertions(+), 931 deletions(-) create mode 100644 docs/install/cache.md create mode 100644 docs/install/index.md create mode 100644 docs/install/lockfile.md create mode 100644 docs/install/registries.md create mode 100644 docs/install/utilities.md create mode 100644 docs/install/workspaces.md create mode 100644 docs/runtime/autoimport.md create mode 100644 docs/runtime/bun-apis.md rename docs/{project => runtime}/configuration.md (83%) create mode 100644 docs/runtime/jsx.md rename docs/{ecosystem/nodejs.md => runtime/nodejs-apis.md} (99%) rename docs/{ecosystem => runtime}/typescript.md (62%) create mode 100644 docs/templates.md create mode 100644 docs/test/writing.md diff --git a/docs/api/ffi.md b/docs/api/ffi.md index 13b50f9c7f..d6ed23f470 100644 --- a/docs/api/ffi.md +++ b/docs/api/ffi.md @@ -1,5 +1,7 @@ Use the built-in `bun:ffi` module to efficiently call native libraries from JavaScript. It works with languages that support the C ABI (Zig, Rust, C/C++, C#, Nim, Kotlin, etc). +## Usage (`bun:ffi`) + To print the version number of `sqlite3`: ```ts @@ -227,11 +229,7 @@ const lib = linkSymbols({ }, }); -const [major, minor, patch] = [ - lib.symbols.getMajor(), - lib.symbols.getMinor(), - lib.symbols.getPatch(), -]; +const [major, minor, patch] = [lib.symbols.getMajor(), lib.symbols.getMinor(), lib.symbols.getPatch()]; ``` ## Callbacks @@ -251,13 +249,10 @@ const { }, }); -const searchIterator = new JSCallback( - (ptr, length) => /hello/.test(new CString(ptr, length)), - { - returns: "bool", - args: ["ptr", "usize"], - }, -); +const searchIterator = new JSCallback((ptr, length) => /hello/.test(new CString(ptr, length)), { + returns: "bool", + args: ["ptr", "usize"], +}); const str = Buffer.from("wwutwutwutwutwutwutwutwutwutwutut\0", "utf8"); if (search(ptr(str), searchIterator)) { @@ -278,7 +273,7 @@ When you're done with a JSCallback, you should call `close()` to free the memory **⚡️ Performance tip** — For a slight performance boost, directly pass `JSCallback.prototype.ptr` instead of the `JSCallback` object: ```ts -const onResolve = new JSCallback((arg) => arg === 42, { +const onResolve = new JSCallback(arg => arg === 42, { returns: "bool", args: ["i32"], }); diff --git a/docs/api/file-io.md b/docs/api/file-io.md index 35d639422e..ca78338d27 100644 --- a/docs/api/file-io.md +++ b/docs/api/file-io.md @@ -1,10 +1,10 @@ {% callout %} -**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/ecosystem/nodejs#node_fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. +**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/runtime/nodejs-apis#node_fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. {% /callout %} Bun provides a set of optimized APIs for reading and writing files. -## Reading files +## Reading files (`Bun.file()`) `Bun.file(path): BunFile` @@ -56,7 +56,7 @@ Bun.stdout; Bun.stderr; ``` -## Writing files +## Writing files (`Bun.write()`) `Bun.write(destination, data): Promise` diff --git a/docs/api/globals.md b/docs/api/globals.md index d490695904..f5fc411dc3 100644 --- a/docs/api/globals.md +++ b/docs/api/globals.md @@ -34,7 +34,7 @@ Bun implements the following globals. - [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) - Node.js -- See [Node.js > `Buffer`](/docs/ecosystem/nodejs#node_buffer) +- See [Node.js > `Buffer`](/docs/runtime/nodejs-apis#node_buffer) --- @@ -172,7 +172,7 @@ Bun implements the following globals. - [`global`](https://nodejs.org/api/globals.html#global) - Node.js -- See [Node.js > `global`](/docs/ecosystem/nodejs#node_global). +- See [Node.js > `global`](/docs/runtime/nodejs-apis#node_global). --- @@ -214,7 +214,7 @@ Bun implements the following globals. - [`process`](https://nodejs.org/api/process.html) - Node.js -- See [Node.js > `process`](/docs/ecosystem/nodejs#node_process) +- See [Node.js > `process`](/docs/runtime/nodejs-apis#node_process) --- diff --git a/docs/api/http.md b/docs/api/http.md index 3e11299dd3..3ebdafab99 100644 --- a/docs/api/http.md +++ b/docs/api/http.md @@ -1,8 +1,8 @@ {% callout %} -**Note** — This page documents the `Bun.serve` API. This API is heavily optimized and represents the recommended way to build HTTP servers in Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/ecosystem/nodejs#node_http) implementation of the Node.js [`http`](https://nodejs.org/api/http.html) and [`https`](https://nodejs.org/api/https.html) modules. +**Note** — This page documents the `Bun.serve` API. This API is heavily optimized and represents the recommended way to build HTTP servers in Bun. Existing Node.js projects may use Bun's [nearly complete](/docs/runtime/nodejs-apis#node_http) implementation of the Node.js [`http`](https://nodejs.org/api/http.html) and [`https`](https://nodejs.org/api/https.html) modules. {% /callout %} -## Send a request +## Send a request (`fetch()`) Bun implements the Web `fetch` API for making HTTP requests. The `fetch` function is available in the global scope. @@ -13,7 +13,7 @@ console.log(result.icons[0].src); // => "/logo-square.jpg" ``` -## Start a server +## Start a server (`Bun.serve()`) Start an HTTP server in Bun with `Bun.serve`. diff --git a/docs/api/spawn.md b/docs/api/spawn.md index 100969aa35..1ef81f1b7e 100644 --- a/docs/api/spawn.md +++ b/docs/api/spawn.md @@ -1,6 +1,6 @@ Spawn child processes with `Bun.spawn` or `Bun.spawnSync`. -## Spawn a process +## Spawn a process (`Bun.spawn()`) Provide a command as an array of strings. The result of `Bun.spawn()` is a `Bun.Subprocess` object. @@ -28,9 +28,7 @@ By default, the input stream of the subprocess is undefined; it can be configure ```ts const proc = Bun.spawn(["cat"], { - stdin: await fetch( - "https://raw.githubusercontent.com/oven-sh/bun/main/examples/hashing.js", - ), + stdin: await fetch("https://raw.githubusercontent.com/oven-sh/bun/main/examples/hashing.js"), }); const text = await new Response(proc.stdout).text(); @@ -183,7 +181,7 @@ const proc = Bun.spawn(["echo", "hello"]); proc.unref(); ``` -## Blocking API +## 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. @@ -245,12 +243,7 @@ namespace SpawnOptions { stdin?: SpawnOptions.Readable; stdout?: SpawnOptions.Writable; stderr?: SpawnOptions.Writable; - onExit?: ( - proc: Subprocess, - exitCode: number | null, - signalCode: string | null, - error: Error | null, - ) => void; + onExit?: (proc: Subprocess, exitCode: number | null, signalCode: string | null, error: Error | null) => void; } type Readable = @@ -262,7 +255,7 @@ namespace SpawnOptions { | BunFile | ArrayBufferView | number; - + type Writable = | "pipe" | "inherit" @@ -307,10 +300,10 @@ interface SyncSubprocess { type ReadableSubprocess = Subprocess; type WritableSubprocess = Subprocess<"pipe", any, any>; type PipedSubprocess = Subprocess<"pipe", "pipe", "pipe">; -type NullSubprocess = Subprocess +type NullSubprocess = Subprocess; type ReadableSyncSubprocess = SyncSubprocess<"pipe", "pipe">; -type NullSyncSubprocess = SyncSubprocess +type NullSyncSubprocess = SyncSubprocess; type Signal = | "SIGABRT" diff --git a/docs/api/tcp.md b/docs/api/tcp.md index 5e04dd3482..999464f3fb 100644 --- a/docs/api/tcp.md +++ b/docs/api/tcp.md @@ -1,6 +1,6 @@ Use Bun's native TCP API implement performance sensitive systems like database clients, game servers, or anything that needs to communicate over TCP (instead of HTTP). This is a low-level API intended for library authors and for advanced use cases. -## Start a server +## Start a server (`Bun.listen()`) To start a TCP server with `Bun.listen`: @@ -90,7 +90,7 @@ server.stop(true); server.unref(); ``` -## Create a connection +## Create a connection (`Bun.connect()`) Use `Bun.connect` to connect to a TCP server. Specify the server to connect to with `hostname` and `port`. TCP clients can define the same set of handlers as `Bun.listen`, plus a couple client-specific handlers. @@ -136,7 +136,7 @@ const server = Bun.listen({ /* config */ }) // reloads handlers for all active server-side sockets server.reload({ - socket: + socket: { data(){ // new 'data' handler } diff --git a/docs/api/utils.md b/docs/api/utils.md index ce3d0d6f97..59167b2b7d 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -94,9 +94,7 @@ test("peek", () => { // If we peek a rejected promise, it: // - returns the error // - does not mark the promise as handled - const rejected = Promise.reject( - new Error("Successfully tested promise rejection"), - ); + const rejected = Promise.reject(new Error("Successfully tested promise rejection")); expect(peek(rejected).message).toBe("Successfully tested promise rejection"); }); ``` @@ -128,7 +126,7 @@ const currentFile = import.meta.url; Bun.openInEditor(currentFile); ``` -You can override this via the `debug.editor` setting in your [`bunfig.toml`](/docs/project/configuration) +You can override this via the `debug.editor` setting in your [`bunfig.toml`](/docs/runtime/configuration) ```toml-diff#bunfig.toml + [debug] @@ -142,5 +140,5 @@ Bun.openInEditor(import.meta.url, { editor: "vscode", // or "subl" line: 10, column: 5, -}) +}); ``` diff --git a/docs/api/websockets.md b/docs/api/websockets.md index f04d10fc60..0c40a05c03 100644 --- a/docs/api/websockets.md +++ b/docs/api/websockets.md @@ -12,7 +12,7 @@ Internally Bun's WebSocket implementation is built on [uWebSockets](https://github.com/uNetworking/uWebSockets). {% /callout %} -## Create a client +## Connect to a WebSocket server To connect to an external socket server, create an instance of `WebSocket` with the constructor. @@ -46,7 +46,7 @@ socket.addEventListener("close", event => {}); socket.addEventListener("error", event => {}); ``` -## Create a server +## Create a WebSocket server Below is a simple WebSocket server built with `Bun.serve`, in which all incoming requests are [upgraded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) to WebSocket connections in the `fetch` handler. The socket handlers are declared in the `websocket` parameter. diff --git a/docs/cli/bunx.md b/docs/cli/bunx.md index 0e6787fc11..fe7bd80a2b 100644 --- a/docs/cli/bunx.md +++ b/docs/cli/bunx.md @@ -1,8 +1,8 @@ {% callout %} -**Note** — `bunx` is an alias for `bun x` +**Note** — `bunx` is an alias for `bun x`. The `bunx` CLI will be auto-installed when you install `bun`. {% /callout %} -Use `bunx` to auto-install and run packages from `npm`. The `bunx` CLI will be auto-installed when you install `bun`. +Use `bunx` to auto-install and run packages from `npm`. It's Bun's equivalent of `npx` or `yarn dlx`. ```bash $ bunx cowsay "Hello world!" @@ -50,7 +50,7 @@ $ bunx my-cli --foo bar ## Shebangs -By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using [Bun's runtime](/docs/runtime), even if the executable indicates otherwise. To do so, include the `--bun` flag. +By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using Bun's runtime, even if the executable indicates otherwise. To do so, include the `--bun` flag. ```bash $ bunx --bun my-cli @@ -66,7 +66,7 @@ $ bunx my-cli --bun # bad {% /callout %} -## Environment variables + diff --git a/docs/cli/create.md b/docs/cli/create.md index a6dc90c2ca..393378eed4 100644 --- a/docs/cli/create.md +++ b/docs/cli/create.md @@ -1,3 +1,29 @@ +## `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 diff --git a/docs/cli/install.md b/docs/cli/install.md index 4018a1d198..811c9ec95c 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -1,8 +1,8 @@ -The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project. +The `bun` CLI contains a Node.js-compatible package manager designed to be a dramatically faster replacement for `npm`, `yarn`, and `pnpm`. It's a standalone tool that will work in pre-existing Node.js projects; if your project has a `package.json`, `bun install` can help you speed up your workflow. {% callout %} -**⚡️ 80x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 80x faster. +**⚡️ 25x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 25x faster. {% image src="https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png" height="200" /%} @@ -23,7 +23,9 @@ sudo apt install --install-recommends linux-generic-hwe-20.04 {% /details %} -## Install dependencies +## Manage dependencies + +### `bun install` To install all dependencies of a project: @@ -84,13 +86,12 @@ dryRun = false {% /details %} -## Add and remove packages +### `bun add` -To add or remove a particular package: +To add a particular package: ```bash $ bun add preact -$ bun remove preact ``` To specify a version, version range, or tag: @@ -147,222 +148,15 @@ To view a complete list of options for a given command: $ bun add --help ``` -## Git dependencies +### `bun remove` -To add a dependency from a git repository: +To remove a dependency: ```bash -$ bun install git@github.com:moment/moment.git +$ bun remove preact ``` -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" - } -} -``` - -## Global cache - -All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached. - -{% details summary="Configuring cache behavior" %} - -```toml -[install.cache] -# the directory to use for the cache -dir = "~/.bun/install/cache" - -# when true, don't load from the global cache. -# Bun may still write to node_modules/.cache -disable = false - -# when true, always resolve the latest versions from the registry -disableManifest = false -``` - -{% /details %} - -### Minimizing re-downloads - -Bun strives to avoid re-downloading packages mutiple times. When installing a package, if the cache already contains a version in the range specified by `package.json`, Bun will use the cached package instead of downloading it again. - -{% details summary="Installation details" %} -If the semver version has pre-release suffix (`1.0.0-beta.0`) or a build suffix (`1.0.0+20220101`), it is replaced with a hash of that value instead, to reduce the chances of errors associated with long file paths. - -When the `node_modules` folder exists, before installing, Bun checks that `node_modules` contains all expected packages with appropriate versions. If so `bun install` completes. Bun uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`. - -If a package is missing or has a version incompatible with the `package.json`, Bun checks for a compatible module in the cache. If found, it is installed into `node_modules`. Otherwise, the package will be downloaded from the registry then installed. -{% /details %} - -### Fast copying - -Once a package is downloaded into the cache, Bun still needs to copy those files into `node_modules`. Bun uses the fastest syscalls available to perform this task. On Linux, it uses hardlinks; on macOS, it uses `clonefile`. - -### Saving disk space - -Since Bun uses hardlinks to "copy" a module into a project's `node_modules` directory on Linux, the contents of the package only exist in a single location on disk, greatly reducing the amount of disk space dedicated to `node_modules`. - -This benefit does not extend to macOS, which uses `clonefile` for performance reasons. - -{% details summary="Installation strategies" %} -This behavior is configurable with the `--backend` flag, which is respected by all of Bun's package management commands. - -- **`hardlink`**: Default on Linux. -- **`clonefile`** Default on macOS. -- **`clonefile_each_dir`**: Similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`. -- **`copyfile`**: The fallback used when any of the above fail. It is the slowest option. On macOS, it uses `fcopyfile()`; on Linux it uses `copy_file_range()`. - **`symlink`**: Currently used only `file:` (and eventually `link:`) dependencies. To prevent infinite loops, it skips symlinking the `node_modules` folder. - -If you install with `--backend=symlink`, Node.js won't resolve node_modules of dependencies unless each dependency has its own `node_modules` folder or you pass `--preserve-symlinks` to `node`. See [Node.js documentation on `--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks). - -```bash -$ bun install --backend symlink -$ node --preserve-symlinks ./foo.js -``` - -Bun's runtime does not currently expose an equivalent of `--preserve-symlinks`. -{% /details %} - -## Lockfile - -Running `bun install` will create a binary lockfile called `bun.lockb`. - -#### Why is it binary? - -In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles. - -#### How do I inspect it? - -Run `bun install -y` to generate a Yarn-compatible `yarn.lock` (v1) that can be inspected more easily. - -#### Platform-specific dependencies? - -Bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won’t change between platforms/architectures even if the packages ultimately installed do change. - -#### What does the lockfile store? - -Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to, and which version (or equivalent). - -#### Why is it fast? - -It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order. - -#### Can I opt out? - -To install without creating a lockfile: - -```bash -$ bun install --no-save -``` - -To install a Yarn lockfile _in addition_ to `bun.lockb`. - -{% codetabs %} - -```bash#CLI flag -$ bun install --yarn -``` - -```toml#bunfig.toml -[install.lockfile] -# whether to save a non-Bun lockfile alongside bun.lockb -# only "yarn" is supported -print = "yarn" -``` - -{% /codetabs %} - -{% details summary="Configuring lockfile" %} - -```toml -[install.lockfile] - -# path to read bun.lockb from -path = "bun.lockb" - -# path to save bun.lockb to -savePath = "bun.lockb" - -# whether to save the lockfile to disk -save = true - -# whether to save a non-Bun lockfile alongside bun.lockb -# only "yarn" is supported -print = "yarn" -``` - -{% /details %} - -## Workspaces - -Bun supports [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description) in `package.json`. Workspaces make it easy to develop complex software as a _monorepo_ consisting of several independent packages. - -To try it, specify a list of sub-packages in the `workspaces` field of your `package.json`; it's conventional to place these sub-packages in a directory called `packages`. - -```json -{ - "name": "my-project", - "version": "1.0.0", - "workspaces": ["packages/*"] -} -``` - -{% callout %} -**Glob support** — Bun v0.5.8 added support for simple globs for workspace names, with a "*/" at the end. Nothing too fancy. -{% /callout %} - -This has a couple major benefits. - -- **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency with `bun add`. If package `b` depends on `a`, `bun install` will symlink your local `packages/a` directory into the `node_modules` folder of `b`, instead of trying to download it from the npm registry. -- **Dependencies can be de-duplicated.** If `a` and `b` share a common dependency, it will be _hoisted_ to the root `node_modules` directory. This reduces redundant disk usage and minimizes "dependency hell" issues associated with having multiple versions of a package installed simultaneously. - -{% callout %} -⚡️ **Speed** — Installs are fast, even for big monorepos. Bun installs the [Remix](https://github.com/remix-run/remix) monorepo in about `500ms` on Linux. - -- 28x faster than `npm install` -- 12x faster than `yarn install` (v1) -- 8x faster than `pnpm install` - -{% image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" /%} -{% /callout %} - -## Registries - -The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`: - -```toml -[install] -# set default registry as a string -registry = "https://registry.npmjs.org" -# set a token -registry = { url = "https://registry.npmjs.org", token = "123456" } -# set a username/password -registry = "https://username:password@registry.npmjs.org" -``` - -To configure a private registry scoped to a particular organization: - -```toml -[install.scopes] -# registry as string -"@myorg1" = "https://username:password@registry.myorg.com/" - -# registry with username/password -# you can reference environment variables -"@myorg2" = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" } - -# registry with token -"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" } -``` - -## Linking and unlinking +## Local packages (`bun link`) Use `bun link` in a local directory to register the current package as a "linkable" package. @@ -403,44 +197,56 @@ This will add `cool-pkg` to the `dependencies` field of your app's package.json } ``` -## Utilities +## Git dependencies -The `bun pm` command group provides a set of utilities for working with Bun's package manager. - -To print the path to the `bin` directory for the local project: +To add a dependency from a git repository: ```bash -$ bun pm bin -/path/to/current/project/node_modules/.bin +$ bun install git@github.com:moment/moment.git ``` -To get the path to the global `bin` directory: +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. -```bash -$ bun pm bin -<$HOME>/.bun/bin +```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" + } +} ``` -To print a list of packages installed in the current project and their resolved versions, excluding their dependencies. Use the `--all` flag to print the entire tree, including all nth-order dependencies. +## Tarball dependencies -```bash -$ bun pm ls -/path/to/project node_modules (5) -├── eslint@8.33.0 -├── react@18.2.0 -├── react-dom@18.2.0 -├── typescript@4.8.4 -└── zod@3.20.1 +A package name can correspond to a publically hosted `.tgz` file. During `bun install`, Bun will download and install the package from the specified tarball URL, rather than from the package registry. + +```json#package.json +{ + "dependencies": { + "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz" + } +} ``` -To print the path to Bun's global module cache: +## CI/CD -```bash -$ bun pm cache -``` - -To clear Bun's global module cache: - -```bash -$ bun pm cache rm +Looking to speed up your CI? Use the official `oven-sh/setup-bun` action to install `bun` in a GitHub Actions pipeline. + +```yaml#.github/workflows/release.yml +name: bun-types +jobs: + build: + name: build-app + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Install bun + uses: oven-sh/setup-bun@v1 + - name: Install dependencies + run: bun install + - name: Build app + run: bun run build ``` diff --git a/docs/cli/run.md b/docs/cli/run.md index 133f3e1ec4..7a5f8e9d2a 100644 --- a/docs/cli/run.md +++ b/docs/cli/run.md @@ -1,31 +1,38 @@ The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin). -## Running a file + + + + +## Run a file {% callout %} Compare to `node ` {% /callout %} -Bun can execute `.js`, `.jsx`, `.ts`, and `.tsx` files. Every file is transpiled to vanilla JavaScript by Bun's fast native transpiler before being executed. For details on Bun's runtime, refer to the [Bun runtime](/docs/runtime) documentation. - -```ts#foo.ts -import { z } from "zod"; - -const schema = z.string() -const result = schema.parse("Billie Eilish"); -console.log(result); -``` - -To run a file in Bun: +Use `bun run` to execute a source file. ```bash -$ bun foo.ts -Billie Eilish +$ bun run index.js ``` -If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](/docs/cli/install#global-cache). For full details on this algorithm, refer to [Runtime > Modules](/docs/runtime/modules). +Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed. -## Running a package script +```bash +$ bun run index.js +$ bun run index.jsx +$ bun run index.ts +$ bun run index.tsx +``` + +The "naked" `bun` command is equivalent to `bun run`. + +```bash +$ bun index.tsx +``` + +## Run a `package.json` script {% note %} Compare to `npm run