diff --git a/docs/api/ffi.md b/docs/api/ffi.md index d6ed23f470..0beae17446 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 13a285693f..0a32b567d0 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 ec32274d7d..770b46478e 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 b040272b5d..a85f9d08c4 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 c9190875a7..cba440f01c 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 8b166e3e85..de2dc69946 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 b8b7f7a8ed..defc9e18c4 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 cdf6b76c5b..417b77148b 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 3d79434230..fd80513aef 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 2b52ae7dab..4c27378947 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 3c23d8a4e5..0d145721ae 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 3a0e668151..bc51614e37 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 9b323a8aa8..a608a8950a 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 3680573b06..65c4842cc2 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 7d95418611..0a70f6f059 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 30ce2dad45..3a2e88c5ad 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 857e11aae6..3cad145f98 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 14887b239f..39e185b3c0 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 69f4cc619a..3f14cd9b17 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 360f4add2d..412b78a85a 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 cf5a20e191..f2a45048a6 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 `/*` globs in `"workspaces"`. Full glob syntax (e.g. `**` and `?`) is not yet supported (soon!). +**Glob support** — Bun supports simple `/*` 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 576c94e20a..a93f915fea 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 ``` + + ```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 ` +- `bun run ` + +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 a08cfa294f..6eb74f0daf 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 40f117c1dc..e0be3da29b 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 d147230249..38a2badd2a 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 7f0b04c28a..07f3f0f666 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 a10ac0cff7..a4174fa252 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 a483efbec3..0135d9363a 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 2073158043..dd48dfa46f 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 2bdc1fe507..72504e6645 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 39eea32786..5bf80ffb43 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 98c822274f..1deb7cc408 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 e80e95eda6..52e25fba6a 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