bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/{cli/run.md → runtime/index.mdx}

@@ -1,93 +1,78 @@
-The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin).
-
-## Performance
-
-Bun is designed to start fast and run fast.
-
-Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
-
-{% table %}
-
 ---
-
-- `bun hello.js`
-- `5.2ms`
-
+title: Bun Runtime
+description: Execute JavaScript/TypeScript files, package.json scripts, and executable packages with Bun's fast runtime.
 ---
 
-- `node hello.js`
-- `25.1ms`
+import Run from "/snippets/cli/run.mdx";
 
-{% /table %}
-{% caption content="Running a simple Hello World script on Linux" /%}
+The Bun Runtime is designed to start fast and run fast.
 
-<!-- {% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%} -->
+Under the hood, Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
 
-<!-- ## Speed -->
+| Command         | Time     |
+| --------------- | -------- |
+| `bun hello.js`  | `5.2ms`  |
+| `node hello.js` | `25.1ms` |
 
-<!--
-Performance sensitive APIs like `Buffer`, `fetch`, and `Response` are heavily profiled and optimized. Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. It starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. -->
+This benchmark is based on running a simple Hello World script on Linux
 
 ## Run a file
 
-{% callout %}
-Compare to `node <file>`
-{% /callout %}
-
 Use `bun run` to execute a source file.
 
-```bash
-$ bun run index.js
+```bash terminal icon="terminal"
+bun run index.js
 ```
 
 Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed.
 
-```bash
-$ bun run index.js
-$ bun run index.jsx
-$ bun run index.ts
-$ bun run index.tsx
+```bash terminal icon="terminal"
+bun run index.js
+bun run index.jsx
+bun run index.ts
+bun run index.tsx
 ```
 
 Alternatively, you can omit the `run` keyword and use the "naked" command; it behaves identically.
 
-```bash
-$ bun index.tsx
-$ bun index.js
+```bash terminal icon="terminal"
+bun index.tsx
+bun index.js
 ```
 
 ### `--watch`
 
 To run a file in watch mode, use the `--watch` flag.
 
-```bash
-$ bun --watch run index.tsx
+```bash terminal icon="terminal"
+bun --watch run index.tsx
 ```
 
-{% callout %}
-**Note** — When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
+<Note>
+When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
 
 ```bash
-$ bun --watch run dev # ✔️ do this
-$ bun run dev --watch # ❌ don't do this
+bun --watch run dev # ✔️ do this
+bun run dev --watch # ❌ don't do this
 ```
 
 Flags that occur at the end of the command will be ignored and passed through to the `"dev"` script itself.
-{% /callout %}
+
+</Note>
 
 ## Run a `package.json` script
 
-{% note %}
+<Note>
 Compare to `npm run <script>` or `yarn <script>`
-{% /note %}
+</Note>
 
 ```sh
-$ bun [bun flags] run <script> [script flags]
+bun [bun flags] run <script> [script flags]
 ```
 
 Your `package.json` can define a number of named `"scripts"` that correspond to shell commands.
 
-```json
+```json package.json icon="file-json"
 {
   // ... other fields
   "scripts": {
@@ -99,29 +84,33 @@ Your `package.json` can define a number of named `"scripts"` that correspond to
 
 Use `bun run <script>` to execute these scripts.
 
-```bash
-$ bun run clean
- $ rm -rf dist && echo 'Done.'
- Cleaning...
- Done.
+```bash terminal icon="terminal"
+bun run clean
+rm -rf dist && echo 'Done.'
+```
+
+```txt
+Cleaning...
+Done.
 ```
 
 Bun executes the script command in a subshell. On Linux & macOS, it checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`. On windows, it uses [bun shell](https://bun.com/docs/runtime/shell) to support bash-like syntax and many common commands.
 
-{% callout %}
-⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.
-{% /callout %}
+<Note>⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.</Note>
 
 Scripts can also be run with the shorter command `bun <script>`, however if there is a built-in bun command with the same name, the built-in command takes precedence. In this case, use the more explicit `bun run <script>` command to execute your package script.
 
-```bash
-$ bun run dev
+```bash terminal icon="terminal"
+bun run dev
 ```
 
 To see a list of available scripts, run `bun run` without any arguments.
 
-```bash
-$ bun run
+```bash terminal icon="terminal"
+bun run
+```
+
+```txt
 quickstart scripts:
 
  bun run clean
@@ -139,7 +128,7 @@ Bun respects lifecycle hooks. For instance, `bun run clean` will execute `precle
 
 It's common for `package.json` scripts to reference locally-installed CLIs like `vite` or `next`. These CLIs are often JavaScript files marked with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate that they should be executed with `node`.
 
-```js
+```js cli.js icon="/icons/javascript.svg"
 #!/usr/bin/env node
 
 // do stuff
@@ -147,16 +136,8 @@ It's common for `package.json` scripts to reference locally-installed CLIs like
 
 By default, Bun respects this shebang and executes the script with `node`. However, you can override this behavior with the `--bun` flag. For Node.js-based CLIs, this will run the CLI with Bun instead of Node.js.
 
-```bash
-$ bun run --bun vite
-```
-
-### `--no-addons`
-
-Disable native addons and use the `node-addons` export condition.
-
-```bash
-$ bun --no-addons run server.js
+```bash terminal icon="terminal"
+bun run --bun vite
 ```
 
 ### Filtering
@@ -166,7 +147,7 @@ In monorepos containing multiple packages, you can use the `--filter` argument t
 Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
 For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
 
-```bash
+```bash terminal icon="terminal"
 bun run --filter 'ba*' <script>
 ```
 
@@ -174,28 +155,26 @@ will execute `<script>` in both `bar` and `baz`, but not in `foo`.
 
 Find more details in the docs page for [filter](https://bun.com/docs/cli/filter#running-scripts-with-filter).
 
-### `--workspaces`
-
-Run scripts across all workspaces in the monorepo:
-
-```bash
-bun run --workspaces test
-```
-
 ## `bun run -` to pipe code from stdin
 
 `bun run -` lets you read JavaScript, TypeScript, TSX, or JSX from stdin and execute it without writing to a temporary file first.
 
-```bash
-$ echo "console.log('Hello')" | bun run -
+```bash terminal icon="terminal"
+echo "console.log('Hello')" | bun run -
+```
+
+```txt
 Hello
 ```
 
 You can also use `bun run -` to redirect files into Bun. For example, to run a `.js` file as if it were a `.ts` file:
 
-```bash
-$ echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
-$ bun run - < secretly-typescript.js
+```bash terminal icon="terminal"
+echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
+bun run - < secretly-typescript.js
+```
+
+```txt
 This is TypeScript!
 ```
 
@@ -205,13 +184,13 @@ For convenience, all code is treated as TypeScript with JSX support when using `
 
 Control the depth of object inspection in console output with the `--console-depth` flag.
 
-```bash
-$ bun --console-depth 5 run index.tsx
+```bash terminal icon="terminal"
+bun --console-depth 5 run index.tsx
 ```
 
 This sets how deeply nested objects are displayed in `console.log()` output. The default depth is `2`. Higher values show more nested properties but may produce verbose output for complex objects.
 
-```js
+```ts console.ts icon="/icons/typescript.svg"
 const nested = { a: { b: { c: { d: "deep" } } } };
 console.log(nested);
 // With --console-depth 2 (default): { a: { b: [Object] } }
@@ -222,20 +201,12 @@ console.log(nested);
 
 In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance.
 
-```bash
-$ bun --smol run index.tsx
+```bash terminal icon="terminal"
+bun --smol run index.tsx
 ```
 
 This causes the garbage collector to run more frequently, which can slow down execution. However, it can be useful in environments with limited memory. Bun automatically adjusts the garbage collector's heap size based on the available memory (accounting for cgroups and other memory limits) with and without the `--smol` flag, so this is mostly useful for cases where you want to make the heap size grow more slowly.
 
-## `--user-agent`
-
-**`--user-agent <string>`** - Set User-Agent header for all `fetch()` requests:
-
-```bash
-bun --user-agent "MyBot/1.0" run index.tsx
-```
-
 ## Resolution order
 
 Absolute paths and paths starting with `./` or `.\\` are always executed as source files. Unless using `bun run`, running a file with an allowed extension will prefer the file over a package.json script.
@@ -247,15 +218,6 @@ When there is a package.json script and a file with the same name, `bun run` pri
 3. Binaries from project packages, eg `bun add eslint && bun run eslint`
 4. (`bun run` only) System commands, eg `bun run ls`
 
-### `--unhandled-rejections`
-
-Configure how unhandled promise rejections are handled:
-
-```bash
-$ bun --unhandled-rejections=throw script.js  # Throw exception (terminate immediately)
-$ bun --unhandled-rejections=strict script.js # Throw exception (emit rejectionHandled if handled later)
-$ bun --unhandled-rejections=warn script.js   # Print warning to stderr (default in Node.js)
-$ bun --unhandled-rejections=none script.js   # Silently ignore
-```
+---
 
-{% bunCLIUsage command="run" /%}
+<Run />

package/docs/runtime/jsx.mdx

@@ -0,0 +1,115 @@
+---
+title: "JSX"
+description: "Built-in JSX and TSX support in Bun with configurable transpilation options"
+---
+
+Bun supports `.jsx` and `.tsx` files out of the box. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
+
+```ts react.tsx icon="/icons/typescript.svg"
+function Component(props: {message: string}) {
+  return (
+    <body>
+      <h1 style={{color: 'red'}}>{props.message}</h1>
+    </body>
+  );
+}
+
+console.log(<Component message="Hello world!" />);
+```
+
+## Configuration
+
+Bun reads your `tsconfig.json` or `jsconfig.json` configuration files to determines how to perform the JSX transform internally. To avoid using either of these, the following options can also be defined in [`bunfig.toml`](/runtime/bunfig).
+
+The following compiler options are respected.
+
+### [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
+
+How JSX constructs are transformed into vanilla JavaScript internally. The table below lists the possible values of `jsx`, along with their transpilation of the following simple JSX component:
+
+```tsx
+<Box width={5}>Hello</Box>
+```
+
+| Compiler options                                    | Transpiled output                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `json<br/>{<br/>  "jsx": "react"<br/>}<br/>`        | `tsx<br/>import { createElement } from "react";<br/>createElement("Box", { width: 5 }, "Hello");<br/>`                                                                                                                                                                                                                                                                                                                                                                    |
+| `json<br/>{<br/>  "jsx": "react-jsx"<br/>}<br/>`    | `tsx<br/>import { jsx } from "react/jsx-runtime";<br/>jsx("Box", { width: 5 }, "Hello");<br/>`                                                                                                                                                                                                                                                                                                                                                                            |
+| `json<br/>{<br/>  "jsx": "react-jsxdev"<br/>}<br/>` | `tsx<br/>import { jsxDEV } from "react/jsx-dev-runtime";<br/>jsxDEV(<br/>  "Box",<br/>  { width: 5, children: "Hello" },<br/>  undefined,<br/>  false,<br/>  undefined,<br/>  this,<br/>);<br/>`<br/><br/>The `jsxDEV` variable name is a convention used by React. The `DEV` suffix is a visible way to indicate that the code is intended for use in development. The development version of React is slower and includes additional validity checks & debugging tools. |
+| `json<br/>{<br/>  "jsx": "preserve"<br/>}<br/>`     | `tsx<br/>// JSX is not transpiled<br/>// "preserve" is not supported by Bun currently<br/><Box width={5}>Hello</Box><br/>`                                                                                                                                                                                                                                                                                                                                                |
+
+### [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
+
+<Note>**Note** — Only applicable when `jsx` is `react`.</Note>
+
+The function name used to represent JSX constructs. Default value is `"createElement"`. This is useful for libraries like [Preact](https://preactjs.com/) that use a different function name (`"h"`).
+
+| Compiler options                                                      | Transpiled output                                                              |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `json<br/>{<br/>  "jsx": "react",<br/>  "jsxFactory": "h"<br/>}<br/>` | `tsx<br/>import { h } from "react";<br/>h("Box", { width: 5 }, "Hello");<br/>` |
+
+### [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
+
+<Note>**Note** — Only applicable when `jsx` is `react`.</Note>
+
+The function name used to represent [JSX fragments](https://react.dev/reference/react/Fragment) such as `<>Hello</>`; only applicable when `jsx` is `react`. Default value is `"Fragment"`.
+
+| Compiler options                                                                                                    | Transpiled output                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `json<br/>{<br/>  "jsx": "react",<br/>  "jsxFactory": "myjsx",<br/>  "jsxFragmentFactory": "MyFragment"<br/>}<br/>` | `tsx<br/>// input<br/><>Hello</>;<br/><br/>// output<br/>import { myjsx, MyFragment } from "react";<br/>myjsx(MyFragment, null, "Hello");<br/>` |
+
+### [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)
+
+<Note>**Note** — Only applicable when `jsx` is `react-jsx` or `react-jsxdev`.</Note>
+
+The module from which the component factory function (`createElement`, `jsx`, `jsxDEV`, etc) will be imported. Default value is `"react"`. This will typically be necessary when using a component library like Preact.
+
+| Compiler options                                                                                                   | Transpiled output                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jsonc<br/>{<br/>  "jsx": "react",<br/>  // jsxImportSource is not defined<br/>  // default to "react"<br/>}<br/>` | `tsx<br/>import { jsx } from "react/jsx-runtime";<br/>jsx("Box", { width: 5, children: "Hello" });<br/>`                                                                                                                                        |
+| `jsonc<br/>{<br/>  "jsx": "react-jsx",<br/>  "jsxImportSource": "preact",<br/>}<br/>`                              | `tsx<br/>import { jsx } from "preact/jsx-runtime";<br/>jsx("Box", { width: 5, children: "Hello" });<br/>`                                                                                                                                       |
+| `jsonc<br/>{<br/>  "jsx": "react-jsxdev",<br/>  "jsxImportSource": "preact",<br/>}<br/>`                           | `tsx<br/>// /jsx-runtime is automatically appended<br/>import { jsxDEV } from "preact/jsx-dev-runtime";<br/>jsxDEV(<br/>  "Box",<br/>  { width: 5, children: "Hello" },<br/>  undefined,<br/>  false,<br/>  undefined,<br/>  this,<br/>);<br/>` |
+
+### JSX pragma
+
+All of these values can be set on a per-file basis using _pragmas_. A pragma is a special comment that sets a compiler option in a particular file.
+
+| Pragma                                   | Equivalent config                                                  |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| `ts<br/>// @jsx h<br/>`                  | `jsonc<br/>{<br/>  "jsxFactory": "h",<br/>}<br/>`                  |
+| `ts<br/>// @jsxFrag MyFragment<br/>`     | `jsonc<br/>{<br/>  "jsxFragmentFactory": "MyFragment",<br/>}<br/>` |
+| `ts<br/>// @jsxImportSource preact<br/>` | `jsonc<br/>{<br/>  "jsxImportSource": "preact",<br/>}<br/>`        |
+
+## Logging
+
+Bun implements special logging for JSX to make debugging easier. Given the following file:
+
+```tsx index.tsx icon="/icons/typescript.svg"
+import { Stack, UserCard } from "./components";
+
+console.log(
+  <Stack>
+    <UserCard name="Dom" bio="Street racer and Corona lover" />
+    <UserCard name="Jakob" bio="Super spy and Dom's secret brother" />
+  </Stack>,
+);
+```
+
+Bun will pretty-print the component tree when logged:
+
+<Frame>![JSX logging output](https://github.com/oven-sh/bun/assets/3084745/d29db51d-6837-44e2-b8be-84fc1b9e9d97)</Frame>
+
+## Prop punning
+
+The Bun runtime also supports "prop punning" for JSX. This is a shorthand syntax useful for assigning a variable to a prop with the same name.
+
+```tsx react.tsx icon="/icons/typescript.svg"
+function Div(props: {className: string;}) {
+  const {className} = props;
+
+  // without punning
+  return <div className={className} />;
+  // with punning
+  return <div {className} />;
+}
+```