diff options
37 files changed, 180 insertions, 158 deletions
diff --git a/docs/api/ffi.md b/docs/api/ffi.md index d6ed23f47..0beae1744 100644 --- a/docs/api/ffi.md +++ b/docs/api/ffi.md @@ -229,7 +229,11 @@ 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 @@ -249,10 +253,13 @@ 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)) { @@ -376,10 +383,6 @@ If you want to track when a `TypedArray` is no longer in use from JavaScript, yo #### From C, Rust, Zig, etc -{% callout %} -**Note** — Available in Bun v0.1.8 and later. -{% /callout %} - If you want to track when a `TypedArray` is no longer in use from C or FFI, you can pass a callback and an optional context pointer to `toArrayBuffer` or `toBuffer`. This function is called at some point later, once the garbage collector frees the underlying `ArrayBuffer` JavaScript object. The expected signature is the same as in [JavaScriptCore's C API](https://developer.apple.com/documentation/javascriptcore/jstypedarraybytesdeallocator?language=objc): diff --git a/docs/api/hashing.md b/docs/api/hashing.md index 13a285693..0a32b567d 100644 --- a/docs/api/hashing.md +++ b/docs/api/hashing.md @@ -6,10 +6,6 @@ Bun implements the `createHash` and `createHmac` functions from [`node:crypto`]( ## `Bun.password` -{% callout %} -**Note** — Added in Bun 0.6.8. -{% /callout %} - `Bun.password` is a collection of utility functions for hashing and verifying passwords with various cryptographically secure algorithms. ```ts diff --git a/docs/api/http.md b/docs/api/http.md index ec32274d7..770b46478 100644 --- a/docs/api/http.md +++ b/docs/api/http.md @@ -140,12 +140,6 @@ Bun.serve({ }); ``` -{% callout %} - -**Note** — Earlier versions of Bun supported passing a file path as `keyFile` and `certFile`; this has been deprecated as of `v0.6.3`. - -{% /callout %} - If your private key is encrypted with a passphrase, provide a value for `passphrase` to decrypt it. ```ts-diff @@ -231,7 +225,7 @@ serve({ ⚡️ **Speed** — Bun automatically uses the [`sendfile(2)`](https://man7.org/linux/man-pages/man2/sendfile.2.html) system call when possible, enabling zero-copy file transfers in the kernel—the fastest way to send files. {% /callout %} -**[v0.3.0+]** You can send part of a file using the [`slice(start, end)`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice) method on the `Bun.file` object. This automatically sets the `Content-Range` and `Content-Length` headers on the `Response` object. +You can send part of a file using the [`slice(start, end)`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice) method on the `Bun.file` object. This automatically sets the `Content-Range` and `Content-Length` headers on the `Response` object. ```ts Bun.serve({ diff --git a/docs/api/spawn.md b/docs/api/spawn.md index b040272b5..a85f9d08c 100644 --- a/docs/api/spawn.md +++ b/docs/api/spawn.md @@ -28,7 +28,9 @@ 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(); @@ -209,7 +211,7 @@ Bun's `spawnSync` spawns processes 60% faster than the Node.js `child_process` m ```bash $ bun spawn.mjs cpu: Apple M1 Max -runtime: bun 0.2.0 (arm64-darwin) +runtime: bun 1.x (arm64-darwin) benchmark time (avg) (min … max) p75 p99 p995 --------------------------------------------------------- ----------------------------- @@ -230,10 +232,15 @@ A simple reference of the Spawn API and types are shown below. The real types ha ```ts interface Bun { spawn(command: string[], options?: SpawnOptions.OptionsObject): Subprocess; - spawnSync(command: string[], options?: SpawnOptions.OptionsObject): SyncSubprocess; + spawnSync( + command: string[], + options?: SpawnOptions.OptionsObject, + ): SyncSubprocess; spawn(options: { cmd: string[] } & SpawnOptions.OptionsObject): Subprocess; - spawnSync(options: { cmd: string[] } & SpawnOptions.OptionsObject): SyncSubprocess; + spawnSync( + options: { cmd: string[] } & SpawnOptions.OptionsObject, + ): SyncSubprocess; } namespace SpawnOptions { @@ -243,7 +250,12 @@ 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 = diff --git a/docs/api/tcp.md b/docs/api/tcp.md index c9190875a..cba440f01 100644 --- a/docs/api/tcp.md +++ b/docs/api/tcp.md @@ -76,12 +76,6 @@ Bun.listen({ }); ``` -{% callout %} - -**Note** — Earlier versions of Bun supported passing a file path as `keyFile` and `certFile`; this has been deprecated as of `v0.6.3`. - -{% /callout %} - The `key` and `cert` fields expect the _contents_ of your TLS key and certificate. This can be a string, `BunFile`, `TypedArray`, or `Buffer`. ```ts @@ -95,7 +89,7 @@ Bun.listen({ // string key: fs.readFileSync("./key.pem", "utf8"), // array of above - key: [Bun.file('./key1.pem'), Bun.file('./key2.pem')] + key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")], }, }); ``` diff --git a/docs/api/utils.md b/docs/api/utils.md index 8b166e3e8..de2dc6994 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -43,7 +43,7 @@ This is analogous to the [`require.main = module` trick](https://stackoverflow.c ## `Bun.sleep()` -`Bun.sleep(ms: number)` (added in Bun v0.5.6) +`Bun.sleep(ms: number)` Returns a `Promise` that resolves after the given number of milliseconds. @@ -65,7 +65,7 @@ console.log("hello one second later!"); ## `Bun.sleepSync()` -`Bun.sleepSync(ms: number)` (added in Bun v0.5.6) +`Bun.sleepSync(ms: number)` A blocking synchronous version of `Bun.sleep`. @@ -108,7 +108,7 @@ console.log(ls); // null ## `Bun.peek()` -`Bun.peek(prom: Promise)` (added in Bun v0.2.2) +`Bun.peek(prom: Promise)` Reads a promise's result without `await` or `.then`, but only if the promise has already fulfilled or rejected. diff --git a/docs/api/websockets.md b/docs/api/websockets.md index b8b7f7a8e..defc9e18c 100644 --- a/docs/api/websockets.md +++ b/docs/api/websockets.md @@ -12,6 +12,18 @@ Internally Bun's WebSocket implementation is built on [uWebSockets](https://github.com/uNetworking/uWebSockets). {% /callout %} +## Connect to a WebSocket server + +{% callout %} +**🚧** — The `WebSocket` client still does not pass the full [Autobahn test suite](https://github.com/crossbario/autobahn-testsuite) and should not be considered ready for production. +{% /callout %} + +Bun implements the `WebSocket` class. To create a WebSocket client that connects to a `ws://` or `wss://` server, create an instance of `WebSocket`, as you would in the browser. + +```ts +const socket = new WebSocket("ws://localhost:3000"); +``` + ## Start 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/api/workers.md b/docs/api/workers.md index cdf6b76c5..417b77148 100644 --- a/docs/api/workers.md +++ b/docs/api/workers.md @@ -1,5 +1,5 @@ {% callout %} -`Worker` support was added in Bun v0.7.0. +**🚧** — The `Worker` API is still experimental and should not be considered ready for production. {% /callout %} [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) lets you start and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread. diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 3d7943423..fd80513ae 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -52,7 +52,6 @@ Run this with `bun cat.js /path/to/big/file`. ## Reading from standard input ```ts -// As of Bun v0.3.0, console is an AsyncIterable for await (const line of console) { // line of text from stdin console.log(line); diff --git a/docs/bundler/plugins.md b/docs/bundler/plugins.md index 2b52ae7da..4c2737894 100644 --- a/docs/bundler/plugins.md +++ b/docs/bundler/plugins.md @@ -1,7 +1,3 @@ -{% callout %} -**Note** — Introduced in Bun v0.1.11. -{% /callout %} - Bun provides a universal plugin API that can be used to extend both the _runtime_ and _bundler_. Plugins intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to add support for additional file types, like `.scss` or `.yaml`. In the context of Bun's bundler, plugins can be used to implement framework-level features like CSS extraction, macros, and client-server code co-location. diff --git a/docs/bundler/vs-esbuild.md b/docs/bundler/vs-esbuild.md index 3c23d8a4e..0d145721a 100644 --- a/docs/bundler/vs-esbuild.md +++ b/docs/bundler/vs-esbuild.md @@ -1,7 +1,3 @@ -{% callout %} -**Note** — Available in Bun v0.6.0 and later. -{% /callout %} - Bun's bundler API is inspired heavily by [esbuild](https://esbuild.github.io/). Migrating to Bun's bundler from esbuild should be relatively painless. This guide will briefly explain why you might consider migrating to Bun's bundler and provide a side-by-side API comparison reference for those who are already familiar with esbuild's API. There are a few behavioral differences to note. diff --git a/docs/cli/bun-init.md b/docs/cli/bun-init.md index 3a0e66815..bc51614e3 100644 --- a/docs/cli/bun-init.md +++ b/docs/cli/bun-init.md @@ -13,8 +13,6 @@ 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`. -Added in Bun v0.1.7. - #### How is `bun init` different than `bun create`? `bun init` is for blank projects. `bun create` applies templates. diff --git a/docs/cli/install.md b/docs/cli/install.md index 9b323a8aa..a608a8950 100644 --- a/docs/cli/install.md +++ b/docs/cli/install.md @@ -197,7 +197,7 @@ $ cat package.json "version": "1.0.0" } $ bun link -bun link v0.5.7 (7416672e) +bun link v1.x (7416672e) Success! Registered "cool-pkg" To use cool-pkg in a project, run: diff --git a/docs/cli/run.md b/docs/cli/run.md index 3680573b0..65c4842cc 100644 --- a/docs/cli/run.md +++ b/docs/cli/run.md @@ -42,10 +42,6 @@ $ bun --watch run index.tsx ### `--smol` -{% callout %} -Added in Bun v0.7.0. -{% /callout %} - In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance. ```bash diff --git a/docs/guides/ecosystem/discordjs.md b/docs/guides/ecosystem/discordjs.md index 7d9541861..0a70f6f05 100644 --- a/docs/guides/ecosystem/discordjs.md +++ b/docs/guides/ecosystem/discordjs.md @@ -2,7 +2,7 @@ name: Create a Discord bot --- -Discord.js works [out of the box](https://bun.sh/blog/bun-v0.6.7) with Bun. Let's write a simple bot. First create a directory and initialize it with `bun init`. +Discord.js works out of the box with Bun. Let's write a simple bot. First create a directory and initialize it with `bun init`. ```bash mkdir my-bot diff --git a/docs/guides/ecosystem/nuxt.md b/docs/guides/ecosystem/nuxt.md index 30ce2dad4..3a2e88c5a 100644 --- a/docs/guides/ecosystem/nuxt.md +++ b/docs/guides/ecosystem/nuxt.md @@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app ✔ Which package manager would you like to use? bun ◐ Installing dependencies... -bun install v0.8.1 (16b4bf34) +bun install v1.x (16b4bf34) + @nuxt/devtools@0.8.2 + nuxt@3.7.0 785 packages installed [2.67s] diff --git a/docs/guides/ecosystem/vite.md b/docs/guides/ecosystem/vite.md index 857e11aae..3cad145f9 100644 --- a/docs/guides/ecosystem/vite.md +++ b/docs/guides/ecosystem/vite.md @@ -8,7 +8,7 @@ While Vite currently works with Bun, it has not been heavily optimized, nor has --- -Vite works out of the box with Bun (v0.7 and later). Get started with one of Vite's templates. +Vite works out of the box with Bun. Get started with one of Vite's templates. ```bash $ bunx create-vite my-app diff --git a/docs/guides/test/run-tests.md b/docs/guides/test/run-tests.md index 14887b239..39e185b3c 100644 --- a/docs/guides/test/run-tests.md +++ b/docs/guides/test/run-tests.md @@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are ```sh $ bun test -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test.test.js: ✓ add [0.87ms] @@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru ```sh $ bun test test3 -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test3.test.js: ✓ add [1.40ms] @@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test ```sh $ bun test -t add -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test.test.js: ✓ add [1.79ms] diff --git a/docs/guides/test/snapshot.md b/docs/guides/test/snapshot.md index 69f4cc619..3f14cd9b1 100644 --- a/docs/guides/test/snapshot.md +++ b/docs/guides/test/snapshot.md @@ -22,7 +22,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e ```sh $ bun test test/snap -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test/snap.test.ts: ✓ snapshot [1.48ms] @@ -65,7 +65,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an ```sh $ bun test -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test/snap.test.ts: ✓ snapshot [1.05ms] @@ -82,7 +82,7 @@ To update snapshots, use the `--update-snapshots` flag. ```sh $ bun test --update-snapshots -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test/snap.test.ts: ✓ snapshot [0.86ms] diff --git a/docs/guides/test/update-snapshots.md b/docs/guides/test/update-snapshots.md index 360f4add2..412b78a85 100644 --- a/docs/guides/test/update-snapshots.md +++ b/docs/guides/test/update-snapshots.md @@ -33,7 +33,7 @@ To regenerate snapshots, use the `--update-snapshots` flag. ```sh $ bun test --update-snapshots -bun test v0.8.0 (9c68abdb) +bun test v1.x (9c68abdb) test/snap.test.ts: ✓ snapshot [0.86ms] diff --git a/docs/install/workspaces.md b/docs/install/workspaces.md index cf5a20e19..f2a45048a 100644 --- a/docs/install/workspaces.md +++ b/docs/install/workspaces.md @@ -11,7 +11,7 @@ To try it, specify a list of sub-packages in the `workspaces` field of your `pac ``` {% callout %} -**Glob support** — Bun v0.5.8 added support for simple `<directory>/*` globs in `"workspaces"`. Full glob syntax (e.g. `**` and `?`) is not yet supported (soon!). +**Glob support** — Bun supports simple `<directory>/*` globs in `"workspaces"`. Full glob syntax (e.g. `**` and `?`) is not yet supported. {% /callout %} This has a couple major benefits. diff --git a/docs/installation.md b/docs/installation.md index 576c94e20..a93f915fe 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,17 +1,21 @@ Bun ships as a single executable that can be installed a few different ways. -{% callout %} -**Windows users** — Bun does not currently provide a native Windows build. We're working on this; progress can be tracked at [this issue](https://github.com/oven-sh/bun/issues/43). In the meantime, use one of the installation methods below for Windows Subsystem for Linux. +## 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. {% /callout %} {% codetabs %} -```bash#Native +```bash#macOS/Linux_(curl) $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL ``` +<!-- ```sh#Windows +PS> irm https://bun.sh/install | iex +``` --> + ```bash#NPM $ npm install -g bun # the last `npm` command you'll ever need ``` @@ -32,6 +36,20 @@ $ proto install bun {% /codetabs %} +## Windows + +Bun provides a _limited, experimental_ native build for Windows. At the moment, only the Bun runtime is supported. + +- `bun <file>` +- `bun run <file>` + +The test runner, package manager, and bundler are still under development. The following commands have been disabled. + +- `bun test` +- `bun install/add/remove` +- `bun link/unlink` +- `bun build` + ## Upgrading Once installed, the binary can upgrade itself. diff --git a/docs/project/development.md b/docs/project/development.md index a08cfa294..6eb74f0da 100644 --- a/docs/project/development.md +++ b/docs/project/development.md @@ -131,7 +131,7 @@ The binary will be located at `packages/debug-bun-{platform}-{arch}/bun-debug`. ```bash $ packages/debug-bun-*/bun-debug --version -bun 0.x.y__dev +bun 1.x.y__dev ``` Note: `make setup` is just an alias for the following: diff --git a/docs/project/licensing.md b/docs/project/licensing.md index 40f117c1d..e0be3da29 100644 --- a/docs/project/licensing.md +++ b/docs/project/licensing.md @@ -95,7 +95,7 @@ Bun statically links these libraries: --- -- Parts of Tigerbeetle's IO code https://github.com/tigerbeetle/tigerbeetle/blob/532c8b70b9142c17e07737ab6d3da68d7500cbca/src/io/windows.zig#L1 +- Parts of [Tigerbeetle's IO code](https://github.com/tigerbeetle/tigerbeetle/blob/532c8b70b9142c17e07737ab6d3da68d7500cbca/src/io/windows.zig#L1) - Apache 2.0 licensed {% /table %} diff --git a/docs/runtime/autoimport.md b/docs/runtime/autoimport.md index d14723024..38a2badd2 100644 --- a/docs/runtime/autoimport.md +++ b/docs/runtime/autoimport.md @@ -1,7 +1,3 @@ -{% callout %} -**Note** — Added in Bun v0.3.0 -{% /callout %} - If no `node_modules` directory is found in the working directory or higher, Bun will abandon Node.js-style module resolution in favor of the **Bun module resolution algorithm**. Under Bun-style module resolution, all imported packages are auto-installed on the fly into a [global module cache](/docs/install/cache) during execution (the same cache used by [`bun install`](/docs/cli/install)). diff --git a/docs/runtime/hot.md b/docs/runtime/hot.md index 7f0b04c28..07f3f0f66 100644 --- a/docs/runtime/hot.md +++ b/docs/runtime/hot.md @@ -1,7 +1,7 @@ Bun supports two kinds of automatic reloading via CLI flags: -- `--watch` mode, which hard restarts Bun's process when imported files change (introduced in Bun v0.5.9) -- `--hot` mode, which soft reloads the code (without restarting the process) when imported files change (introduced in Bun v0.2.0) +- `--watch` mode, which hard restarts Bun's process when imported files change/ +- `--hot` mode, which soft reloads the code (without restarting the process) when imported files change. ## `--watch` mode diff --git a/docs/runtime/index.md b/docs/runtime/index.md index a10ac0cff..a4174fa25 100644 --- a/docs/runtime/index.md +++ b/docs/runtime/index.md @@ -103,7 +103,11 @@ import bunfig from "./bunfig.toml"; ## WASM -As of v0.5.2, experimental support exists for WASI, the [WebAssembly System Interface](https://github.com/WebAssembly/WASI). To run a `.wasm` binary with Bun: +{% callout %} +🚧 **Experimental** +{% /callout %} + +Bun has experimental support for WASI, the [WebAssembly System Interface](https://github.com/WebAssembly/WASI). To run a `.wasm` binary with Bun: ```bash $ bun ./my-wasm-app.wasm diff --git a/docs/runtime/loaders.md b/docs/runtime/loaders.md index a483efbec..0135d9363 100644 --- a/docs/runtime/loaders.md +++ b/docs/runtime/loaders.md @@ -36,10 +36,6 @@ $ bun run react.tsx ## Text files -{% callout %} -Supported in Bun v0.6.0 canary. -{% /callout %} - Text files can be imported as strings. {% codetabs %} @@ -67,7 +63,11 @@ import data from "./data.toml"; ## WASM -As of v0.5.2, experimental support exists for WASI, the [WebAssembly System Interface](https://github.com/WebAssembly/WASI). To run a `.wasm` binary with Bun: +{% callout %} +🚧 **Experimental** +{% /callout %} + +Bun has experimental support for WASI, the [WebAssembly System Interface](https://github.com/WebAssembly/WASI). To run a `.wasm` binary with Bun: ```bash $ bun ./my-wasm-app.wasm diff --git a/docs/runtime/modules.md b/docs/runtime/modules.md index 207315804..dd48dfa46 100644 --- a/docs/runtime/modules.md +++ b/docs/runtime/modules.md @@ -161,20 +161,15 @@ If you aren't a TypeScript user, you can create a [`jsconfig.json`](https://code ## CommonJS -Bun has native support for CommonJS modules (added in Bun v0.6.5). ES Modules are the recommended module format, but CommonJS modules are still widely used in the Node.js ecosystem. Bun supports both module formats, so that existing CommonJS packages can be used. +Bun has native support for CommonJS modules. ES Modules are the recommended module format, but CommonJS modules are still widely used in the Node.js ecosystem. Bun supports both module formats. -In Bun's JavaScript runtime, `require` can be used by both ES Modules and CommonJS modules. - -In Bun, you can `require()` ESM modules from CommonJS modules. +In Bun's JavaScript runtime, `require` can be used by both ES Modules and CommonJS modules. If the target module is an ES Module, `require` returns the module namespace object (equivalent to `import * as`). If the target module is a CommonJS module, `require` returns the `module.exports` object (as in Node.js). | Module Type | `require()` | `import * as` | | ----------- | ---------------- | ----------------------------------------------------------------------- | | ES Module | Module Namespace | Module Namespace | | CommonJS | module.exports | `default` is `module.exports`, keys of module.exports are named exports | -If the target module is an ES Module, `require` returns the module namespace object (equivalent to `import * as`). -If the target module is a CommonJS module, `require` returns the `module.exports` object. - ### What is a CommonJS module? In 2016, ECMAScript added support for [ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). ES Modules are the standard for JavaScript modules. However, millions of npm packages still use CommonJS modules. @@ -202,19 +197,10 @@ const myStuff = require("./my-commonjs.cjs"); ### Importing ESM from CommonJS ```ts -// this works in Bun v0.6.5+ -// It does not work in Node.js +// this works in Bun but not Node.js const { stuff } = require("./my-esm.mjs"); ``` -### Importing CommonJS from CommonJS - -You can `require()` CommonJS modules from CommonJS modules. - -```ts -const { stuff } = require("./my-commonjs.cjs"); -``` - #### Top-level await If you are using top-level await, you must use `import()` to import ESM modules from CommonJS modules. @@ -228,11 +214,17 @@ import("./my-esm.js").then(({ stuff }) => { const { stuff } = require("./my-esm.js"); ``` -#### Low-level details of CommonJS interop in Bun +{% details summary="Low-level details of CommonJS interop in Bun" %} -Bun's JavaScript runtime has native support for CommonJS as of Bun v0.6.5. +Bun's JavaScript runtime has native support for CommonJS. When Bun's JavaScript transpiler detects usages of `module.exports`, it treats the file as CommonJS. The module loader will then wrap the transpiled module in a function shaped like this: -When Bun's JavaScript transpiler detects usages of `module.exports`, it treats the file as CommonJS. The module loader will then wrap the transpiled module in a function shaped like this: +### Importing CommonJS from CommonJS + +You can `require()` CommonJS modules from CommonJS modules. + +```ts +const { stuff } = require("./my-commonjs.cjs"); +``` ```js (function (module, exports, require) { @@ -245,3 +237,5 @@ When Bun's JavaScript transpiler detects usages of `module.exports`, it treats t Once the CommonJS module is successfully evaluated, a Synthetic Module Record is created with the `default` ES Module [export set to `module.exports`](https://github.com/oven-sh/bun/blob/9b6913e1a674ceb7f670f917fc355bb8758c6c72/src/bun.js/bindings/CommonJSModuleRecord.cpp#L212-L213) and keys of the `module.exports` object are re-exported as named exports (if the `module.exports` object is an object). When using Bun's bundler, this works differently. The bundler will wrap the CommonJS module in a `require_${moduleName}` function which returns the `module.exports` object. + +{% /details %} diff --git a/docs/runtime/nodejs-apis.md b/docs/runtime/nodejs-apis.md index 2bdc1fe50..72504e664 100644 --- a/docs/runtime/nodejs-apis.md +++ b/docs/runtime/nodejs-apis.md @@ -529,7 +529,7 @@ The table below lists all globals implemented by Node.js and Bun's current compa ### [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) -🟢 Fully implemented. Added in Bun 0.5.7. +🟢 Fully implemented. ### [`global`](https://nodejs.org/api/globals.html#global) @@ -859,7 +859,7 @@ The table below lists all globals implemented by Node.js and Bun's current compa - {% anchor id="node_formdata" %} [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) {% /anchor %} - 🟢 -- Fully implemented. Added in Bun 0.5.7. +- Fully implemented. --- diff --git a/docs/runtime/plugins.md b/docs/runtime/plugins.md index 39eea3278..5bf80ffb4 100644 --- a/docs/runtime/plugins.md +++ b/docs/runtime/plugins.md @@ -1,7 +1,3 @@ -{% callout %} -**Note** — Introduced in Bun v0.1.11. -{% /callout %} - Bun provides a universal plugin API that can be used to extend both the _runtime_ and [_bundler_](/docs/bundler). Plugins intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to add support for additional file types, like `.scss` or `.yaml`. In the context of Bun's bundler, plugins can be used to implement framework-level features like CSS extraction, macros, and client-server code co-location. diff --git a/docs/runtime/web-apis.md b/docs/runtime/web-apis.md index 98c822274..1deb7cc40 100644 --- a/docs/runtime/web-apis.md +++ b/docs/runtime/web-apis.md @@ -32,7 +32,7 @@ The following Web APIs are partially or completely supported. --- - WebSockets -- [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) +- [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) (_not production ready_) --- diff --git a/docs/templates.md b/docs/templates.md index e80e95eda..52e25fba6 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -24,33 +24,56 @@ Press `enter` to accept the default answer for each prompt, or pass the `-y` fla ## `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: +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` + +```sh +$ bun create template [<destination>] +``` + +Assuming you don't have a [local template](#local-templates) with the same name, this command will download and execute the `create-<template>` package from npm. The following two commands will behave identically: + +```sh +$ bun create remix +$ bunx create-remix +``` + +Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions. + +### From GitHub + +This will download the contents of the GitHub repo to disk. ```bash -$ bun create <template> # an official template (remote) -$ bun create <username>/<repo> # a GitHub repo (remote) -$ bun create <local-template> # a custom template (local) +$ bun create <user>/<repo> +$ bun create github.com/<user>/<repo> ``` -Running `bun create` performs the following steps: +Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used. -- 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. +```bash +$ bun create <user>/<repo> mydir +$ bun create github.com/<user>/<repo> mydir +``` + +Bun will perform the following steps: + +- Download the template +- Copy all template files into the destination folder - Install dependencies with `bun install`. - Initialize a fresh Git repo. Opt out with the `--no-git` flag. - Run the template's configured `start` script, if defined. -### Official templates +{% callout %} +By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files. +{% /callout %} + +<!-- ### Official templates The following official templates are available. @@ -73,9 +96,9 @@ Welcome to bun! Create a new project by pasting any of the following: {% 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 %} +{% /callout %} --> -### GitHub repos +<!-- ### GitHub repos A template of the form `<username>/<repo>` will be downloaded from GitHub. @@ -90,9 +113,9 @@ $ bun create github.com/ahfarmer/calculator ./myapp $ bun create https://github.com/ahfarmer/calculator ./myapp ``` -Bun installs the files as they currently exist current default branch (usually `main` or `master`). Unlike `git clone` it doesn't download the commit history or configure a remote. +Bun installs the files as they currently exist current default branch (usually `main` or `master`). Unlike `git clone` it doesn't download the commit history or configure a remote. --> -### Local templates +### From a local template {% callout %} **⚠️ Warning** — Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it already exists! Be careful. @@ -124,26 +147,9 @@ Then, create a `package.json` file in that directory with the following contents You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template. -{% table %} - ---- +#### Setup logic -- `postinstall` -- runs after installing dependencies - ---- - -- `preinstall` -- runs before installing dependencies - -<!-- --- - -- `start` -- a command to auto-start the application --> - -{% /table %} - -Each of these can correspond to a string or array of strings. An array of commands will be executed in order. Here is an example: +You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`. ```json { @@ -162,11 +168,27 @@ Each of these can correspond to a string or array of strings. An array of comman } ``` -When cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder. +The following fields are supported. Each of these can correspond to a string or array of strings. An array of commands will be executed in order. + +{% table %} + +--- + +- `postinstall` +- runs after installing dependencies + +--- + +- `preinstall` +- runs before installing dependencies + +{% /table %} + +After cloniing a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder. -### Reference +## Reference -#### CLI flags +### CLI flags {% table %} @@ -195,7 +217,7 @@ When cloning a template, `bun create` will automatically remove the `"bun-create {% /table %} -#### Environment variables +### Environment variables {% table %} diff --git a/docs/test/coverage.md b/docs/test/coverage.md index 503b5abf6..4a9beeb9d 100644 --- a/docs/test/coverage.md +++ b/docs/test/coverage.md @@ -43,10 +43,6 @@ coverageSkipTestFiles = true # default false ### Coverage thresholds -{% callout %} -**Note** — Support for coverage reporting was added in Bun v0.7.3. -{% /callout %} - It is possible to specify a coverage threshold in `bunfig.toml`. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure. ```toml diff --git a/docs/test/dom.md b/docs/test/dom.md index 3eb897745..98ab8101c 100644 --- a/docs/test/dom.md +++ b/docs/test/dom.md @@ -55,7 +55,7 @@ Let's run this test with `bun test`: ```bash $ bun test -bun test v0.x.y +bun test v1.x dom.test.ts: ✓ dom test [0.82ms] diff --git a/docs/test/time.md b/docs/test/time.md index 4a0f98407..15c8778ad 100644 --- a/docs/test/time.md +++ b/docs/test/time.md @@ -1,4 +1,4 @@ -`bun:test` lets you change what time it is in your tests. This was introduced in Bun v0.6.13. +`bun:test` lets you change what time it is in your tests. This works with any of the following: diff --git a/docs/test/writing.md b/docs/test/writing.md index a99af8b90..f5024a369 100644 --- a/docs/test/writing.md +++ b/docs/test/writing.md @@ -300,12 +300,12 @@ Bun implements the following matchers. Full Jest compatibility is on the roadmap --- - 🟢 -- [`.resolves()`](https://jestjs.io/docs/expect#resolves) (since Bun v0.6.12+) +- [`.resolves()`](https://jestjs.io/docs/expect#resolves) --- - 🟢 -- [`.rejects()`](https://jestjs.io/docs/expect#rejects) (since Bun v0.6.12+) +- [`.rejects()`](https://jestjs.io/docs/expect#rejects) --- @@ -385,7 +385,7 @@ Bun implements the following matchers. Full Jest compatibility is on the roadmap --- - 🟢 -- [`.toBeInstanceOf()`](https://jestjs.io/docs/expect#tobeinstanceofclass) (Bun v0.5.8+) +- [`.toBeInstanceOf()`](https://jestjs.io/docs/expect#tobeinstanceofclass) --- @@ -405,7 +405,7 @@ Bun implements the following matchers. Full Jest compatibility is on the roadmap --- - 🟢 -- [`.toMatchSnapshot()`](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint) (Bun v0.5.8+) +- [`.toMatchSnapshot()`](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint) --- |