bun-types 1.3.2-canary.20251105T140650 → 1.3.2-canary.20251108T140624

package/docs/guides/write-file/{cat.md → cat.mdx}

@@ -1,12 +1,14 @@
 ---
-name: Write a file to stdout
+title: Write a file to stdout
+sidebarTitle: Write file to stdout
+mode: center
 ---
 
 Bun exposes `stdout` as a `BunFile` with the `Bun.stdout` property. This can be used as a destination for [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).
 
 This code writes a file to `stdout` similar to the `cat` command in Unix.
 
-```ts#cat.ts
+```ts cat.ts icon="/icons/typescript.svg"
 const path = "/path/to/file.txt";
 const file = Bun.file(path);
 await Bun.write(Bun.stdout, file);

package/docs/guides/write-file/{file-cp.md → file-cp.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Copy a file to another location
+title: Copy a file to another location
+sidebarTitle: Copy file
+mode: center
 ---
 
 This code snippet copies a file to another location on disk.

package/docs/guides/write-file/{filesink.md → filesink.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write a file incrementally
+title: Write a file incrementally
+sidebarTitle: Incremental write
+mode: center
 ---
 
 Bun provides an API for incrementally writing to a file. This is useful for writing large files, or for writing to a file over a long period of time.

package/docs/guides/write-file/{response.md → response.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write a Response to a file
+title: Write a Response to a file
+sidebarTitle: Write Response
+mode: center
 ---
 
 This code snippet writes a `Response` to disk at a particular path. Bun will consume the `Response` body according to its `Content-Type` header.

package/docs/guides/write-file/{stdout.md → stdout.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write to stdout
+title: Write to stdout
+sidebarTitle: Write to stdout
+mode: center
 ---
 
 The `console.log` function writes to `stdout`. It will automatically append a line break at the end of the printed data.

package/docs/guides/write-file/{stream.md → stream.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Write a ReadableStream to a file
+title: Write a ReadableStream to a file
+sidebarTitle: Write stream
+mode: center
 ---
 
 To write a `ReadableStream` to disk, first create a `Response` instance from the stream. This `Response` can then be written to disk using [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).

package/docs/guides/write-file/{unlink.md → unlink.mdx}

@@ -1,5 +1,7 @@
 ---
-name: Delete a file
+title: Delete a file
+sidebarTitle: Delete file
+mode: center
 ---
 
 The `Bun.file()` function accepts a path and returns a `BunFile` instance. Use the `.delete()` method to delete the file.

package/docs/{index.md → index.mdx}

@@ -1,36 +1,108 @@
+---
+title: Welcome to Bun
+description: Bun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.
+mode: center
+---
+
+<CardGroup>
+  <Card
+    icon="cog"
+    title="Bun Runtime"
+    href="/runtime"
+    cta={
+      <span>
+        Get started with <code>bun run</code>
+      </span>
+    }
+  >
+    A fast JavaScript runtime designed as a drop-in replacement for Node.js
+  </Card>
+  <Card
+    icon="box"
+    title="Bun Package Manager"
+    href="/pm/cli/install"
+    cta={
+      <span>
+        Get started with <code>bun install</code>
+      </span>
+    }
+  >
+    Install packages up to 30x faster than npm with a global cache and workspaces
+  </Card>
+  <Card
+    icon="flask-conical"
+    title="Bun Test Runner"
+    href="/test"
+    cta={
+      <span>
+        Get started with <code>bun test</code>
+      </span>
+    }
+  >
+    Jest-compatible, TypeScript-first tests with snapshots, DOM, and watch mode
+  </Card>
+  <Card
+    icon="combine"
+    title="Bun Bundler"
+    href="/bundler"
+    cta={
+      <span>
+        Get started with <code>bun build</code>
+      </span>
+    }
+  >
+    Bundle TypeScript, JSX, React & CSS for both browsers and servers
+  </Card>
+</CardGroup>
+
+---
+
+## Get Started
+
+Bun ships as a single, dependency-free binary and includes a runtime, package manager, test runner, and bundler. New to Bun?
+
+<CardGroup>
+  <Card icon="download" title="Install Bun" href="/installation">
+    Supported platforms and all install methods.
+  </Card>
+  <Card icon="zap" title="Quickstart" href="/quickstart">
+    Hello world in minutes with Bun.serve.
+  </Card>
+</CardGroup>
+
+---
+
+## What's Inside
+
+- Runtime: Execute JavaScript/TypeScript files and package scripts with near-zero overhead.
+- Package Manager: Fast installs, workspaces, overrides, and audits with `bun install`.
+- Test Runner: Jest-compatible, TypeScript-first tests with snapshots, DOM, and watch mode.
+- Bundler: Native bundling for JS/TS/JSX with splitting, plugins, and HTML imports.
+
+Explore each area using the cards above. Each section is structured with an overview, quick examples, reference, and best practices for fast scanning and deep dives.
+
+---
+
+## What is Bun?
+
 Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called `bun`.
 
 At its core is the _Bun runtime_, a fast JavaScript runtime designed as **a drop-in replacement for Node.js**. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.
 
-```bash
-$ bun run index.tsx  # TS and JSX supported out of the box
+```bash terminal icon="terminal"
+bun run index.tsx  # TS and JSX supported out of the box
 ```
 
 The `bun` command-line tool also implements a test runner, script runner, and Node.js-compatible package manager, all significantly faster than existing tools and usable in existing Node.js projects with little to no changes necessary.
 
-```bash
-$ bun run start                 # run the `start` script
-$ bun install <pkg>             # install a package
-$ bun build ./index.tsx         # bundle a project for browsers
-$ bun test                      # run tests
-$ bunx cowsay 'Hello, world!'   # execute a package
+```bash terminal icon="terminal"
+bun run start                 # run the `start` script
+bun install <pkg>             # install a package
+bun build ./index.tsx         # bundle a project for browsers
+bun test                      # run tests
+bunx cowsay 'Hello, world!'   # execute a package
 ```
 
-Get started with one of the quick links below, or read on to learn more about Bun.
-
-{% block className="gap-2 grid grid-flow-row grid-cols-1 md:grid-cols-2" %}
-{% 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/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" /%}
-{% arrowbutton href="/docs/api/file-io" text="Read and write files" /%}
-{% arrowbutton href="/docs/api/sqlite" text="Run SQLite queries" /%}
-{% arrowbutton href="/docs/cli/test" text="Write and run tests" /%}
-{% /block %}
-
 ## 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)
@@ -42,21 +114,12 @@ But most JavaScript programs don't run in a vacuum. They need a way to access th
 
 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. -->
-
 ### Node.js
 
 Similarly, Node.js is a JavaScript runtime that can be used in non-browser environments, like servers. JavaScript programs executed by Node.js have access to a set of Node.js-specific [globals](https://nodejs.org/api/globals.html) like `Buffer`, `process`, and `__dirname` in addition to built-in modules for performing OS-level tasks like reading/writing files (`node:fs`) and networking (`node:net`, `node:http`). Node.js also implements a CommonJS-based module system and resolution algorithm that pre-dates JavaScript's native module system.
 
-<!-- Bun.js prefers Web API compatibility instead of designing new APIs when possible. Bun.js also implements some Node.js APIs. -->
-
 Bun is designed as a faster, leaner, more modern replacement for Node.js.
 
-<!-- ## Why a new runtime?
-
-Bun is designed as a faster, leaner, more modern replacement for Node.js. Node.js is burdened by ingrained performance issues, backwards compatibility concerns, and slow development velocity—inevitable issues for a project of its age and magnitude. -->
-
 ## Design goals
 
 Bun is designed from the ground-up with today's JavaScript ecosystem in mind.
@@ -64,14 +127,7 @@ Bun is designed from the ground-up with today's JavaScript ecosystem in mind.
 - **Speed**. Bun processes start [4x faster than Node.js](https://twitter.com/jarredsumner/status/1499225725492076544) currently (try it yourself!)
 - **TypeScript & JSX support**. You can directly execute `.jsx`, `.ts`, and `.tsx` files; Bun's transpiler converts these to vanilla JavaScript before execution.
 - **ESM & CommonJS compatibility**. The world is moving towards ES modules (ESM), but millions of packages on npm still require CommonJS. Bun recommends ES modules, but supports CommonJS.
-- **Web-standard APIs**. Bun implements standard Web APIs like `fetch`, `WebSocket`, and `ReadableStream`. Bun is powered by the JavaScriptCore engine, which is developed by Apple for Safari, so some APIs like [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) directly use [Safari's implementation](https://github.com/oven-sh/bun/blob/HEAD/src/bun.js/bindings/webcore/JSFetchHeaders.cpp).
-- **Node.js compatibility**. In addition to supporting Node-style module resolution, Bun aims for full compatibility with built-in Node.js globals (`process`, `Buffer`) and modules (`path`, `fs`, `http`, etc.) _This is an ongoing effort that is not complete._ Refer to the [compatibility page](https://bun.com/docs/runtime/nodejs-apis) for the current status.
+- **Web-standard APIs**. Bun implements standard Web APIs like `fetch`, `WebSocket`, and `ReadableStream`. Bun is powered by the JavaScriptCore engine, which is developed by Apple for Safari, so some APIs like [`Headers`](https://developer.mozilla.org/en-US/Web/API/Headers) and [`URL`](https://developer.mozilla.org/en-US/Web/API/URL) directly use [Safari's implementation](https://github.com/oven-sh/bun/blob/HEAD/src/bun.js/bindings/webcore/JSFetchHeaders.cpp).
+- **Node.js compatibility**. In addition to supporting Node-style module resolution, Bun aims for full compatibility with built-in Node.js globals (`process`, `Buffer`) and modules (`path`, `fs`, `http`, etc.) _This is an ongoing effort that is not complete._ Refer to the [compatibility page](/runtime/nodejs-compat) for the current status.
 
 Bun is more than a runtime. The long-term goal is to be a cohesive, infrastructural toolkit for building apps with JavaScript/TypeScript, including a package manager, transpiler, bundler, script runner, test runner, and more.
-
-<!-- - tsconfig.json `"paths"` is natively supported, along with `"exports"` in package.json
-- `fs`, `path`, and `process` from Node.js are partially implemented
-- Web APIs like [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) and more are built-in
-- [`HTMLRewriter`](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/) makes it easy to transform HTML in Bun.js
-- `.env` files automatically load into `process.env` and `Bun.env`
-- top level await -->

package/docs/installation.mdx

@@ -0,0 +1,365 @@
+---
+title: Installation
+description: Install Bun
+---
+
+## Overview
+
+Bun ships as a single, dependency-free executable. You can install it via script, package manager, or Docker across macOS, Linux, and Windows.
+
+<Tip>After installation, verify with `bun --version` and `bun --revision`.</Tip>
+
+## Installation
+
+<Tabs>
+  <Tab title="macOS & Linux">
+
+    <CodeGroup>
+      ```bash curl icon="globe"
+      curl -fsSL https://bun.com/install | bash
+      ```
+
+    </CodeGroup>
+    <Note>
+      **Linux users**  The `unzip` package is required to install Bun. Use `sudo apt install unzip` to install the unzip package. Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Use `uname -r` to check Kernel version.
+      </Note>
+
+  </Tab>
+
+  <Tab title="Windows">
+    <CodeGroup>
+      ```powershell PowerShell icon="terminal"
+      powershell -c "irm bun.sh/install.ps1|iex"
+      ```
+
+    </CodeGroup>
+    <Warning>
+      Bun requires Windows 10 version 1809 or later.
+    </Warning>
+
+
+    For support and discussion, please join the **#windows** channel on our [Discord](https://discord.gg/bun).
+
+  </Tab>
+
+    <Tab title="Package Managers">
+    	<CodeGroup>
+
+    	```bash npm icon="npm"
+    	npm install -g bun # the last `npm` command you'll ever need
+    	```
+
+    	```bash Homebrew icon="/icons/homebrew.svg"
+    	brew install oven-sh/bun/bun
+    	```
+
+    	```bash Scoop icon="terminal"
+    	scoop install bun
+    	```
+
+    	</CodeGroup>
+
+    </Tab>
+
+  <Tab title="Docker">
+    Bun provides a Docker image that supports both Linux x64 and arm64.
+
+    ```bash Docker icon="docker"
+    docker pull oven/bun
+    docker run --rm --init --ulimit memlock=-1:-1 oven/bun
+    ```
+
+    ### Image Variants
+
+    There are also image variants for different operating systems:
+
+    ```bash Docker icon="docker"
+    docker pull oven/bun:debian
+    docker pull oven/bun:slim
+    docker pull oven/bun:distroless
+    docker pull oven/bun:alpine
+    ```
+
+  </Tab>
+</Tabs>
+
+To check that Bun was installed successfully, open a new terminal window and run:
+
+```bash terminal icon="terminal"
+bun --version
+# Output: 1.x.y
+
+# See the precise commit of `oven-sh/bun` that you're using
+bun --revision
+# Output: 1.x.y+b7982ac13189
+```
+
+<Warning>
+  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`.
+</Warning>
+
+<Accordion title="Add Bun to your PATH">
+  <Tabs>
+    <Tab title="macOS & Linux">
+      <Steps>
+        <Step title="Determine which shell you're using">
+        ```bash terminal icon="terminal"
+        echo $SHELL
+        # /bin/zsh  or /bin/bash or /bin/fish
+        ```
+        </Step>
+        <Step title="Open your shell configuration file">
+          - For bash: `~/.bashrc`
+          - For zsh: `~/.zshrc`
+          - For fish: `~/.config/fish/config.fish`
+        </Step>
+        
+        <Step title="Add the Bun directory to PATH">
+          Add this line to your configuration file:
+          ```bash terminal icon="terminal"
+          export BUN_INSTALL="$HOME/.bun"
+          export PATH="$BUN_INSTALL/bin:$PATH"
+          ```
+        </Step>
+        
+        <Step title="Reload your shell configuration">
+          ```bash terminal icon="terminal"
+          source ~/.bashrc  # or ~/.zshrc
+          ```
+        </Step>
+      </Steps>
+    </Tab>
+    <Tab title="Windows">
+      <Steps>
+        <Step title="Determine if the bun binary is properly installed">
+        ```bash terminal icon="terminal"
+        & "$env:USERPROFILE\.bun\bin\bun" --version
+        ```
+
+        If the command runs successfully but `bun --version` is not recognized, it means that bun is not in your system's PATH. To fix this, open a Powershell terminal and run the following command:
+
+        ```bash terminal icon="terminal"
+        [System.Environment]::SetEnvironmentVariable(
+          "Path",
+          [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
+          [System.EnvironmentVariableTarget]::User
+        )
+        ```
+
+        </Step>
+        <Step title="Restart your terminal">
+           After running the command, restart your terminal and test with `bun --version`
+
+          ```bash terminal icon="terminal"
+          bun --version
+          ```
+        </Step>
+      </Steps>
+    </Tab>
+
+  </Tabs>
+</Accordion>
+
+---
+
+## Upgrading
+
+Once installed, the binary can upgrade itself:
+
+```bash terminal icon="terminal"
+bun upgrade
+```
+
+<Tip>
+**Homebrew users** <br />
+To avoid conflicts with Homebrew, use `brew upgrade bun` instead.
+
+**Scoop users** <br />
+To avoid conflicts with Scoop, use `scoop update bun` instead.
+
+</Tip>
+
+---
+
+## Canary Builds
+
+[-> View canary build](https://github.com/oven-sh/bun/releases/tag/canary)
+
+Bun automatically releases an (untested) canary build on every commit to main. To upgrade to the latest canary build:
+
+```bash terminal icon="terminal"
+# Upgrade to latest canary
+bun upgrade --canary
+
+# Switch back to stable
+bun upgrade --stable
+```
+
+The canary build is useful for testing new features and bug fixes before they're released in a stable build. To help the Bun team fix bugs faster, canary builds automatically upload crash reports to Bun's team.
+
+---
+
+## Installing Older Versions
+
+Since Bun is a single binary, you can install older versions by re-running the installer script with a specific version.
+
+<Tabs>
+  <Tab title="Linux & macOS">
+    To install a specific version, pass the git tag to the install script:
+
+    ```bash terminal icon="terminal"
+    curl -fsSL https://bun.com/install | bash -s "bun-v1.3.1"
+    ```
+
+  </Tab>
+  <Tab title="Windows">
+    On Windows, pass the version number to the PowerShell install script:
+
+    ```powershell PowerShell icon="windows"
+    iex "& {$(irm https://bun.com/install.ps1)} -Version 1.3.1"
+    ```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Direct Downloads
+
+To download Bun binaries directly, visit the [releases page on GitHub](https://github.com/oven-sh/bun/releases).
+
+### Latest Version Downloads
+
+<CardGroup cols={2}>
+  <Card
+    icon="/icons/linux.svg"
+    title="Linux x64"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip"
+  >
+    Standard Linux x64 binary
+  </Card>
+  <Card
+    icon="/icons/linux.svg"
+    title="Linux x64 Baseline"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip"
+  >
+    For older CPUs without AVX2
+  </Card>
+  <Card
+    icon="/icons/windows.svg"
+    title="Windows x64"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip"
+  >
+    Standard Windows binary
+  </Card>
+  <Card
+    icon="/icons/windows.svg"
+    title="Windows x64 Baseline"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip"
+  >
+    For older CPUs without AVX2
+  </Card>
+  <Card
+    icon="/icons/apple.svg"
+    title="macOS ARM64"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-aarch64.zip"
+  >
+    Apple Silicon (M1/M2/M3)
+  </Card>
+  <Card
+    icon="/icons/apple.svg"
+    title="macOS x64"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip"
+  >
+    Intel Macs
+  </Card>
+  <Card
+    icon="/icons/linux.svg"
+    title="Linux ARM64"
+    href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip"
+  >
+    ARM64 Linux systems
+  </Card>
+</CardGroup>
+
+### Musl Binaries
+
+For distributions without `glibc` (Alpine Linux, Void Linux):
+
+- [Linux x64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl.zip)
+- [Linux x64 musl baseline](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl-baseline.zip)
+- [Linux ARM64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64-musl.zip)
+
+<Note>
+  If you encounter an error like `bun: /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found`, try using the
+  musl binary. Bun's install script automatically chooses the correct binary for your system.
+</Note>
+
+---
+
+## CPU Requirements
+
+Bun has specific CPU requirements based on the binary you're using:
+
+<Tabs>
+	<Tab title="Standard Builds">
+		**x64 binaries** target the Haswell CPU architecture (AVX and AVX2 instructions required)
+    | Platform | Intel Requirement | AMD Requirement |
+		|----------|-------------------|-----------------| 
+    | x64 | Haswell (4th gen Core) or newer | Excavator or newer |
+	</Tab>
+
+    <Tab title="Baseline Builds">
+    	**x64-baseline binaries** target the Nehalem architecture for older CPUs
+    | Platform | Intel Requirement | AMD Requirement |
+    |----------|-------------------|-----------------|
+    | x64-baseline | Nehalem (1st gen Core) or newer | Bulldozer or newer |
+
+    	<Warning>
+    		Baseline builds are slower than regular builds. Use them only if you encounter an "Illegal
+    		Instruction" error.
+    	</Warning>
+    </Tab>
+
+</Tabs>
+
+<Note>
+  Bun does not support CPUs older than the baseline target, which mandates the SSE4.2 extension. macOS requires version
+  13.0 or later.
+</Note>
+
+---
+
+## Uninstall
+
+To remove Bun from your system:
+
+<Tabs>
+	<Tab title="macOS & Linux">
+  ```bash terminal icon="terminal"
+  rm -rf ~/.bun
+  ```
+  </Tab>
+
+    <Tab title="Windows">
+    	```powershell PowerShell icon="windows"
+    powershell -c ~\.bun\uninstall.ps1
+    ```
+    </Tab>
+
+    <Tab title="Package Managers">
+    	<CodeGroup>
+    		```bash npm icon="npm"
+      npm uninstall -g bun
+      ```
+      ```bash Homebrew icon="/icons/homebrew.svg"
+      brew uninstall bun
+      ```
+      ```bash Scoop icon="terminal"
+      scoop uninstall bun
+      ```
+    	</CodeGroup>
+    </Tab>
+
+</Tabs>