bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/runtime/streams.mdx

@@ -0,0 +1,232 @@
+---
+title: Streams
+description: Use Bun's streams API to work with binary data without loading it all into memory at once
+---
+
+Streams are an important abstraction for working with binary data without loading it all into memory at once. They are commonly used for reading and writing files, sending and receiving network requests, and processing large amounts of data.
+
+Bun implements the Web APIs [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream).
+
+<Note>
+  Bun also implements the `node:stream` module, including
+  [`Readable`](https://nodejs.org/api/stream.html#stream_readable_streams),
+  [`Writable`](https://nodejs.org/api/stream.html#stream_writable_streams), and
+  [`Duplex`](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams). For complete documentation, refer
+  to the [Node.js docs](https://nodejs.org/api/stream.html).
+</Note>
+
+To create a simple `ReadableStream`:
+
+```ts
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue("hello");
+    controller.enqueue("world");
+    controller.close();
+  },
+});
+```
+
+The contents of a `ReadableStream` can be read chunk-by-chunk with `for await` syntax.
+
+```ts
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+
+// hello
+// world
+```
+
+---
+
+## Direct `ReadableStream`
+
+Bun implements an optimized version of `ReadableStream` that avoid unnecessary data copying & queue management logic.
+
+With a traditional `ReadableStream`, chunks of data are _enqueued_. Each chunk is copied into a queue, where it sits until the stream is ready to send more data.
+
+```ts
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue("hello");
+    controller.enqueue("world");
+    controller.close();
+  },
+});
+```
+
+With a direct `ReadableStream`, chunks of data are written directly to the stream. No queueing happens, and there's no need to clone the chunk data into memory. The `controller` API is updated to reflect this; instead of `.enqueue()` you call `.write`.
+
+```ts
+const stream = new ReadableStream({
+  type: "direct", // [!code ++]
+  pull(controller) {
+    controller.write("hello");
+    controller.write("world");
+  },
+});
+```
+
+When using a direct `ReadableStream`, all chunk queueing is handled by the destination. The consumer of the stream receives exactly what is passed to `controller.write()`, without any encoding or modification.
+
+---
+
+## Async generator streams
+
+Bun also supports async generator functions as a source for `Response` and `Request`. This is an easy way to create a `ReadableStream` that fetches data from an asynchronous source.
+
+```ts
+const response = new Response(
+  (async function* () {
+    yield "hello";
+    yield "world";
+  })(),
+);
+
+await response.text(); // "helloworld"
+```
+
+You can also use `[Symbol.asyncIterator]` directly.
+
+```ts
+const response = new Response({
+  [Symbol.asyncIterator]: async function* () {
+    yield "hello";
+    yield "world";
+  },
+});
+
+await response.text(); // "helloworld"
+```
+
+If you need more granular control over the stream, `yield` will return the direct ReadableStream controller.
+
+```ts
+const response = new Response({
+  [Symbol.asyncIterator]: async function* () {
+    const controller = yield "hello";
+    await controller.end();
+  },
+});
+
+await response.text(); // "hello"
+```
+
+---
+
+## `Bun.ArrayBufferSink`
+
+The `Bun.ArrayBufferSink` class is a fast incremental writer for constructing an `ArrayBuffer` of unknown size.
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.write("l");
+sink.write("o");
+
+sink.end();
+// ArrayBuffer(5) [ 104, 101, 108, 108, 111 ]
+```
+
+To instead retrieve the data as a `Uint8Array`, pass the `asUint8Array` option to the `start` method.
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+sink.start({
+  asUint8Array: true, // [!code ++]
+});
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.write("l");
+sink.write("o");
+
+sink.end();
+// Uint8Array(5) [ 104, 101, 108, 108, 111 ]
+```
+
+The `.write()` method supports strings, typed arrays, `ArrayBuffer`, and `SharedArrayBuffer`.
+
+```ts
+sink.write("h");
+sink.write(new Uint8Array([101, 108]));
+sink.write(Buffer.from("lo").buffer);
+
+sink.end();
+```
+
+Once `.end()` is called, no more data can be written to the `ArrayBufferSink`. However, in the context of buffering a stream, it's useful to continuously write data and periodically `.flush()` the contents (say, into a `WriteableStream`). To support this, pass `stream: true` to the constructor.
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+sink.start({
+  stream: true, // [!code ++]
+});
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.flush();
+// ArrayBuffer(5) [ 104, 101, 108 ]
+
+sink.write("l");
+sink.write("o");
+sink.flush();
+// ArrayBuffer(5) [ 108, 111 ]
+```
+
+The `.flush()` method returns the buffered data as an `ArrayBuffer` (or `Uint8Array` if `asUint8Array: true`) and clears internal buffer.
+
+To manually set the size of the internal buffer in bytes, pass a value for `highWaterMark`:
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+sink.start({
+  highWaterMark: 1024 * 1024, // 1 MB  // [!code ++]
+});
+```
+
+---
+
+## Reference
+
+```ts See Typescript Definitions expandable
+/**
+ * Fast incremental writer that becomes an `ArrayBuffer` on end().
+ */
+export class ArrayBufferSink {
+  constructor();
+
+  start(options?: {
+    asUint8Array?: boolean;
+    /**
+     * Preallocate an internal buffer of this size
+     * This can significantly improve performance when the chunk size is small
+     */
+    highWaterMark?: number;
+    /**
+     * On {@link ArrayBufferSink.flush}, return the written data as a `Uint8Array`.
+     * Writes will restart from the beginning of the buffer.
+     */
+    stream?: boolean;
+  }): void;
+
+  write(chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number;
+  /**
+   * Flush the internal buffer
+   *
+   * If {@link ArrayBufferSink.start} was passed a `stream` option, this will return a `ArrayBuffer`
+   * If {@link ArrayBufferSink.start} was passed a `stream` option and `asUint8Array`, this will return a `Uint8Array`
+   * Otherwise, this will return the number of bytes written since the last flush
+   *
+   * This API might change later to separate Uint8ArraySink and ArrayBufferSink
+   */
+  flush(): number | Uint8Array<ArrayBuffer> | ArrayBuffer;
+  end(): ArrayBuffer | Uint8Array<ArrayBuffer>;
+}
+```

package/docs/runtime/templating/create.mdx

@@ -0,0 +1,269 @@
+---
+title: bun create
+description: Create a new Bun project from a React component, a `create-<template>` npm package, a GitHub repo, or a local template
+---
+
+<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.
+</Note>
+
+---
+
+Template a new Bun project with `bun create`. This is a flexible command that can be used to create a new project from a React component, a `create-<template>` npm package, a GitHub repo, or a local template.
+
+If you're looking to create a brand new empty project, use [`bun init`](https://bun.com/docs/cli/init).
+
+## From a React component
+
+`bun create ./MyComponent.tsx` turns an existing React component into a complete dev environment with hot reload and production builds in one command.
+
+```bash
+$ bun create ./MyComponent.jsx # .tsx also supported
+```
+
+<Frame>
+  <video
+    style={{ aspectRatio: "2062 / 1344", width: "100%", height: "100%", objectFit: "contain" }}
+    loop
+    autoPlay
+    muted
+    playsInline
+  >
+    <source
+      src="/images/bun-create-shadcn.mp4"
+      style={{ width: "100%", height: "100%", objectFit: "contain" }}
+      type="video/mp4"
+    />
+  </video>
+</Frame>
+
+<Note>
+🚀 **Create React App Successor** — `bun create <component>` provides everything developers loved about Create React App, but with modern tooling, faster builds, and backend support.
+</Note>
+
+#### How this works
+
+When you run `bun create <component>`, Bun:
+
+1. Uses [Bun's JavaScript bundler](https://bun.com/docs/bundler) to analyze your module graph.
+2. Collects all the dependencies needed to run the component.
+3. Scans the exports of the entry point for a React component.
+4. Generates a `package.json` file with the dependencies and scripts needed to run the component.
+5. Installs any missing dependencies using [`bun install --only-missing`](https://bun.com/docs/cli/install).
+6. Generates the following files:
+   - `${component}.html`
+   - `${component}.client.tsx` (entry point for the frontend)
+   - `${component}.css` (css file)
+7. Starts a frontend dev server automatically.
+
+### Using TailwindCSS with Bun
+
+[TailwindCSS](https://tailwindcss.com/) is an extremely popular utility-first CSS framework used to style web applications.
+
+When you run `bun create <component>`, Bun scans your JSX/TSX file for TailwindCSS class names (and any files it imports). If it detects TailwindCSS class names, it will add the following dependencies to your `package.json`:
+
+```json package.json icon="file-code"
+{
+  "dependencies": {
+    "tailwindcss": "^4",
+    "bun-plugin-tailwind": "latest"
+  }
+}
+```
+
+We also configure `bunfig.toml` to use Bun's TailwindCSS plugin with `Bun.serve()`
+
+```toml bunfig.toml icon="settings"
+[serve.static]
+plugins = ["bun-plugin-tailwind"]
+```
+
+And a `${component}.css` file with `@import "tailwindcss";` at the top:
+
+```css MyComponent.css icon="file-code"
+@import "tailwindcss";
+```
+
+### Using `shadcn/ui` with Bun
+
+[`shadcn/ui`](https://ui.shadcn.com/) is an extremely popular component library tool for building web applications.
+
+`bun create <component>` scans for any shadcn/ui components imported from `@/components/ui`.
+
+If it finds any, it runs:
+
+```bash terminal icon="terminal"
+# Assuming bun detected imports to @/components/ui/accordion and @/components/ui/button
+bunx shadcn@canary add accordion button # and any other components
+```
+
+Since `shadcn/ui` itself uses TailwindCSS, `bun create` also adds the necessary TailwindCSS dependencies to your `package.json` and configures `bunfig.toml` to use Bun's TailwindCSS plugin with `Bun.serve()` as described above.
+
+Additionally, we setup the following:
+
+- `tsconfig.json` to alias `"@/*"` to `"src/*"` or `.` (depending on if there is a `src/` directory)
+- `components.json` so that shadcn/ui knows its a shadcn/ui project
+- `styles/globals.css` file that configures Tailwind v4 in the way that shadcn/ui expects
+- `${component}.build.ts` file that builds the component for production with `bun-plugin-tailwind` configured
+
+`bun create ./MyComponent.jsx` is one of the easiest ways to run code generated from LLMs like [Claude](https://claude.ai) or ChatGPT locally.
+
+## From `npm`
+
+```sh terminal icon="terminal"
+bun create <template> [<destination>]
+```
+
+Assuming you don't have a [local template](#from-a-local-template) with the same name, this command will download and execute the `create-<template>` package from npm. The following two commands will behave identically:
+
+```sh terminal icon="terminal"
+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 terminal icon="terminal"
+bun create <user>/<repo>
+bun create github.com/<user>/<repo>
+```
+
+Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used.
+
+```bash terminal icon="terminal"
+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.
+
+<Note>By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files.</Note>
+
+## From a local template
+
+<Warning>
+  Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it
+  already exists! Be careful.
+</Warning>
+
+Bun's templater can be extended to support custom templates defined on your local file system. These templates should live in one of the following directories:
+
+- `$HOME/.bun-create/<name>`: global templates
+- `<project root>/.bun-create/<name>`: project-specific templates
+
+<Note>You can customize the global template path by setting the `BUN_CREATE_DIR` environment variable.</Note>
+
+To create a local template, navigate to `$HOME/.bun-create` and create a new directory with the desired name of your template.
+
+```bash
+cd $HOME/.bun-create
+mkdir foo
+cd foo
+```
+
+Then, create a `package.json` file in that directory with the following contents:
+
+```json package.json icon="file-json"
+{
+  "name": "foo"
+}
+```
+
+You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template.
+
+#### Setup logic
+
+You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`.
+
+```json package.json icon="file-json"
+{
+  "name": "@bun-examples/simplereact",
+  "version": "0.0.1",
+  "main": "index.js",
+  "dependencies": {
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  },
+  "bun-create": {
+    "preinstall": "echo 'Installing...'", // a single command
+    "postinstall": ["echo 'Done!'"], // an array of commands
+    "start": "bun run echo 'Hello world!'"
+  }
+}
+```
+
+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.
+
+| Field         | Description                         |
+| ------------- | ----------------------------------- |
+| `postinstall` | runs after installing dependencies  |
+| `preinstall`  | runs before installing dependencies |
+
+After cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder.
+
+## Reference
+
+### CLI flags
+
+| Flag           | Description                            |
+| -------------- | -------------------------------------- |
+| `--force`      | Overwrite existing files               |
+| `--no-install` | Skip installing `node_modules` & tasks |
+| `--no-git`     | Don't initialize a git repository      |
+| `--open`       | Start & open in-browser after finish   |
+
+### Environment variables
+
+| Name                                      | Description                                                                                                                                          |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITHUB_API_DOMAIN`                       | If you're using a GitHub enterprise or a proxy, you can customize the GitHub domain Bun pings for downloads                                          |
+| `GITHUB_TOKEN` (or `GITHUB_ACCESS_TOKEN`) | This lets `bun create` work with private repositories or if you get rate-limited. `GITHUB_TOKEN` is chosen over `GITHUB_ACCESS_TOKEN` if both exist. |
+
+<Accordion title={<span>How <code>bun create</code> works</span>}>
+
+When you run `bun create ${template} ${destination}`, here’s what happens:
+
+IF remote template
+
+1. GET `registry.npmjs.org/@bun-examples/${template}/latest` and parse it
+2. GET `registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz`
+3. Decompress & extract `${template}-${latestVersion}.tgz` into `${destination}`
+   - If there are files that would overwrite, warn and exit unless `--force` is passed
+
+IF GitHub repo
+
+1. Download the tarball from GitHub’s API
+2. Decompress & extract into `${destination}`
+   - If there are files that would overwrite, warn and exit unless `--force` is passed
+
+ELSE IF local template
+
+1. Open local template folder
+2. Delete destination directory recursively
+3. Copy files recursively using the fastest system calls available (on macOS `fcopyfile` and Linux, `copy_file_range`). Do not copy or traverse into `node_modules` folder if exists (this alone makes it faster than `cp`)
+
+4. Parse the `package.json` (again!), update `name` to be `${basename(destination)}`, remove the `bun-create` section from the `package.json` and save the updated `package.json` to disk.
+   - IF Next.js is detected, add `bun-framework-next` to the list of dependencies
+   - IF Create React App is detected, add the entry point in `/src/index.{js,jsx,ts,tsx}` to `public/index.html`
+   - IF Relay is detected, add `bun-macro-relay` so that Relay works
+5. Auto-detect the npm client, preferring `pnpm`, `yarn` (v1), and lastly `npm`
+6. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
+7. Run `${npmClient} install` unless `--no-install` is passed OR no dependencies are in package.json
+8. Run any tasks defined in `"bun-create": { "postinstall" }` with the npm client
+9. Run `git init; git add -A .; git commit -am "Initial Commit";`
+   - Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
+   - If there are dependencies, this runs in a separate thread concurrently while node_modules are being installed
+   - Using libgit2 if available was tested and performed 3x slower in microbenchmarks
+
+</Accordion>

package/docs/runtime/templating/init.mdx

@@ -0,0 +1,58 @@
+---
+title: "bun init"
+description: "Scaffold an empty Bun project with the interactive `bun init` command"
+---
+
+import Init from "/snippets/cli/init.mdx";
+
+Get started with Bun by scaffolding a new project with `bun init`.
+
+```bash terminal icon="terminal"
+bun init my-app
+```
+
+```txt
+? Select a project template - Press return to submit.
+❯ Blank
+  React
+  Library
+
+✓ Select a project template: Blank
+
+ + .gitignore
+ + CLAUDE.md
+ + .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc -> CLAUDE.md
+ + index.ts
+ + tsconfig.json (for editor autocomplete)
+ + README.md
+```
+
+Press `enter` to accept the default answer for each prompt, or pass the `-y` flag to auto-accept the defaults.
+
+---
+
+`bun init` is a quick way to start a blank project with Bun. It guesses with sane defaults and is non-destructive when run multiple times.
+
+<Frame>
+  ![Demo](https://user-images.githubusercontent.com/709451/183006613-271960a3-ff22-4f7c-83f5-5e18f684c836.gif)
+</Frame>
+
+It creates:
+
+- a `package.json` file with a name that defaults to the current directory name
+- a `tsconfig.json` file or a `jsconfig.json` file, depending if the entry point is a TypeScript file or not
+- an entry point which defaults to `index.ts` unless any of `index.{tsx, jsx, js, mts, mjs}` exist or the `package.json` specifies a `module` or `main` field
+- a `README.md` file
+
+AI Agent rules (disable with `$BUN_AGENT_RULE_DISABLED=1`):
+
+- a `CLAUDE.md` file when Claude CLI is detected (disable with `CLAUDE_CODE_AGENT_RULE_DISABLED` env var)
+- a `.cursor/rules/*.mdc` file to guide [Cursor AI](https://cursor.sh) to use Bun instead of Node.js and npm when Cursor is detected
+
+If you pass `-y` or `--yes`, it will assume you want to continue without asking questions.
+
+At the end, it runs `bun install` to install `@types/bun`.
+
+---
+
+<Init />