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

package/docs/runtime/{debugger.md → debugger.mdx}

@@ -1,26 +1,30 @@
 ---
-name: Debugging
+title: "Debugging"
+description: "Debug your Bun code with an interactive debugger using WebKit Inspector Protocol"
 ---
 
 Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-inspector-protocol/src/protocol/jsc/index.d.ts), so you can debug your code with an interactive debugger. For demonstration purposes, consider the following simple web server.
 
 ## Debugging JavaScript and TypeScript
 
-```ts#server.ts
+```typescript icon="/icons/typescript.svg" title="server.ts"
 Bun.serve({
-  fetch(req){
+  fetch(req) {
     console.log(req.url);
     return new Response("Hello, world!");
-  }
-})
+  },
+});
 ```
 
 ### `--inspect`
 
 To enable debugging when running code with Bun, use the `--inspect` flag. This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process.
 
-```sh
-$ bun --inspect server.ts
+```sh icon="terminal" title="terminal"
+bun --inspect server.ts
+```
+
+```txt id="terminal"
 ------------------ Bun Inspector ------------------
 Listening at:
   ws://localhost:6499/0tqxs9exrgrm
@@ -42,12 +46,14 @@ The `--inspect-wait` flag behaves identically to `--inspect`, except the code wi
 
 Regardless of which flag you use, you can optionally specify a port number, URL prefix, or both.
 
-```sh
-$ bun --inspect=4000 server.ts
-$ bun --inspect=localhost:4000 server.ts
-$ bun --inspect=localhost:4000/prefix server.ts
+```sh icon="terminal" title="terminal"
+bun --inspect=4000 server.ts
+bun --inspect=localhost:4000 server.ts
+bun --inspect=localhost:4000/prefix server.ts
 ```
 
+---
+
 ## Debuggers
 
 Various debugging tools can connect to this server to provide an interactive debugging experience.
@@ -58,43 +64,61 @@ Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a
 
 Open the provided `debug.bun.sh` URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d" alt="Screenshot of Bun debugger, Console tab" /%}
+<Frame>
+  ![Screenshot of Bun debugger, Console
+  tab](https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d)
+</Frame>
 
 Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number `3` to set a breakpoint on our `console.log(req.url)` statement.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935" alt="screenshot of Bun debugger" /%}
+<Frame>
+  ![screenshot of Bun debugger](https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935)
+</Frame>
 
 Then visit [`http://localhost:3000`](http://localhost:3000) in your web browser. This will send an HTTP request to our `localhost` web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.
 
 Note how the UI has changed.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769" alt="screenshot of Bun debugger" /%}
+<Frame>
+  ![screenshot of Bun debugger](https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769)
+</Frame>
 
 At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681" /%}
+<Frame>
+  ![Bun debugger console](https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681)
+</Frame>
 
 On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the `req` variable.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646" /%}
+<Frame>
+  ![Bun debugger variables](https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646)
+</Frame>
 
 In the upper left of the Sources pane, we can control the execution of the program.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4" /%}
+<Frame>
+  ![Bun debugger controls](https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4)
+</Frame>
 
 Here's a cheat sheet explaining the functions of the control flow buttons.
 
-- _Continue script execution_ — continue running the program until the next breakpoint or exception.
-- _Step over_ — The program will continue to the next line.
-- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
-- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
+- _Continue script execution_ — continue running the program until the next breakpoint or exception.
+- _Step over_ — The program will continue to the next line.
+- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
+- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
 
-{% image src="https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png" /%}
+<Frame>
+  ![Bun debugger execution
+  controls](https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png)
+</Frame>
 
 ### Visual Studio Code Debugger
 
 Experimental support for debugging Bun scripts is available in Visual Studio Code. To use it, you'll need to install the [Bun VSCode extension](https://bun.com/guides/runtime/vscode-debugger).
 
+---
+
 ## Debugging Network Requests
 
 The `BUN_CONFIG_VERBOSE_FETCH` environment variable lets you log network requests made with `fetch()` or `node:http` automatically.
@@ -107,9 +131,9 @@ The `BUN_CONFIG_VERBOSE_FETCH` environment variable lets you log network request
 
 ### Print fetch & node:http requests as curl commands
 
-Bun also supports printing `fetch()` and `node:http` network requests as `curl` commands by setting the environment variable `BUN_CONFIG_VERBOSE_FETCH` to `curl`.
+Bun also supports printing `fetch()` and `node:http` network requests as `curl` commands by setting the environment variable `BUN_CONFIG_VERBOSE_FETCH` to `curl`. This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 process.env.BUN_CONFIG_VERBOSE_FETCH = "curl";
 
 await fetch("https://example.com", {
@@ -121,14 +145,12 @@ await fetch("https://example.com", {
 });
 ```
 
-This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
-
-```sh
-[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.3.2-canary.20251105T140650" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+```txt
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.3.1" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.3.2-canary.20251105T140650
+[fetch] > User-Agent: Bun/1.3.1
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -152,7 +174,7 @@ The `BUN_CONFIG_VERBOSE_FETCH` environment variable is supported in both `fetch(
 
 To print without the `curl` command, set `BUN_CONFIG_VERBOSE_FETCH` to `true`.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 process.env.BUN_CONFIG_VERBOSE_FETCH = "true";
 
 await fetch("https://example.com", {
@@ -164,13 +186,11 @@ await fetch("https://example.com", {
 });
 ```
 
-This prints the following to the console:
-
-```sh
+```txt
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.3.2-canary.20251105T140650
+[fetch] > User-Agent: Bun/1.3.1
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -188,20 +208,12 @@ This prints the following to the console:
 [fetch] < Content-Length: 1256
 ```
 
+---
+
 ## Stacktraces & sourcemaps
 
 Bun transpiles every file, which sounds like it would mean that the stack traces you see in the console would unhelpfully point to the transpiled output. To address this, Bun automatically generates and serves sourcemapped files for every file it transpiles. When you see a stack trace in the console, you can click on the file path and be taken to the original source code, even though it was written in TypeScript or JSX, or has some other transformation applied.
 
-<!-- TODO: uncomment once v1.1.13 regression is fixed (cc @paperclover) -->
-<!-- In Bun, each `Error` object gets four additional properties:
-
-- `line` — the source-mapped line number. This number points to the input source code, not the transpiled output.
-- `column` — the source-mapped column number. This number points to the input source code, not the transpiled output.
-- `originalColumn` — the column number pointing to transpiled source code, without sourcemaps. This number comes from JavaScriptCore.
-- `originalLine` — the line number pointing to transpiled source code, without sourcemaps. This number comes from JavaScriptCore.
-
-These properties are populated lazily when `error.stack` is accessed. -->
-
 Bun automatically loads sourcemaps both at runtime when transpiling files on-demand, and when using `bun build` to precompile files ahead of time.
 
 ### Syntax-highlighted source code preview
@@ -216,7 +228,7 @@ console.log(Bun.inspect(err, { colors: true }));
 
 This prints a syntax-highlighted preview of the source code where the error occurred, along with the error message and stack trace.
 
-```js
+```ts icon="file-code"
 1 | // Create an error
 2 | const err = new Error("Something went wrong");
                 ^
@@ -234,7 +246,7 @@ That's why when you log `error.stack` in Bun, the formatting of `error.stack` is
 
 Bun implements the [V8 Stack Trace API](https://v8.dev/docs/stack-trace-api), which is a set of functions that allow you to manipulate stack traces.
 
-##### Error.prepareStackTrace
+##### `Error.prepareStackTrace`
 
 The `Error.prepareStackTrace` function is a global function that lets you customize the stack trace output. This function is called with the error object and an array of `CallSite` objects and lets you return a custom stack trace.
 
@@ -275,7 +287,7 @@ The `CallSite` object has the following methods:
 
 In some cases, the `Function` object may have already been garbage collected, so some of these methods may return `undefined`.
 
-##### Error.captureStackTrace(error, startFn)
+##### `Error.captureStackTrace(error, startFn)`
 
 The `Error.captureStackTrace` function lets you capture a stack trace at a specific point in your code, rather than at the point where the error was thrown.
 
@@ -283,7 +295,7 @@ This can be helpful when you have callbacks or asynchronous code that makes it d
 
 For example, the below code will make `err.stack` point to the code calling `fn()`, even though the error was thrown at `myInner`.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 const fn = () => {
   function myInner() {
     throw err;
@@ -304,9 +316,7 @@ const fn = () => {
 fn();
 ```
 
-This logs the following:
-
-```sh
+```txt
 Error: here!
     at myInner (file.js:4:15)
     at fn (file.js:8:5)

package/docs/runtime/environment-variables.mdx

@@ -0,0 +1,214 @@
+---
+title: "Environment Variables"
+description: "Read and configure environment variables in Bun, including automatic .env file support"
+---
+
+Bun reads your `.env` files automatically and provides idiomatic ways to read and write your environment variables programmatically. Plus, some aspects of Bun's runtime behavior can be configured with Bun-specific environment variables.
+
+## Setting environment variables
+
+Bun reads the following files automatically (listed in order of increasing precedence).
+
+- `.env`
+- `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
+- `.env.local`
+
+```txt .env icon="settings"
+FOO=hello
+BAR=world
+```
+
+Variables can also be set via the command line.
+
+<CodeGroup>
+
+```sh Linux/macOS icon="terminal"
+FOO=helloworld bun run dev
+```
+
+```sh Windows icon="windows"
+# Using CMD
+set FOO=helloworld && bun run dev
+
+# Using PowerShell
+$env:FOO="helloworld"; bun run dev
+```
+
+</CodeGroup>
+
+<Accordion title="Cross-platform solution with Windows">
+
+For a cross-platform solution, you can use [bun shell](/runtime/shell). For example, the `bun exec` command.
+
+```sh
+bun exec 'FOO=helloworld bun run dev'
+```
+
+On Windows, `package.json` scripts called with `bun run` will automatically use the **bun shell**, making the following also cross-platform.
+
+```json package.json
+"scripts": {
+  "dev": "NODE_ENV=development bun --watch app.ts",
+},
+```
+
+</Accordion>
+
+Or programmatically by assigning a property to `process.env`.
+
+```ts
+process.env.FOO = "hello";
+```
+
+---
+
+## Manually specifying `.env` files
+
+Bun supports `--env-file` to override which specific `.env` file to load. You can use `--env-file` when running scripts in bun's runtime, or when running package.json scripts.
+
+```sh
+bun --env-file=.env.1 src/index.ts
+
+bun --env-file=.env.abc --env-file=.env.def run build
+```
+
+---
+
+## Quotation marks
+
+Bun supports double quotes, single quotes, and template literal backticks:
+
+```txt .env icon="settings"
+FOO='hello'
+FOO="hello"
+FOO=`hello`
+```
+
+### Expansion
+
+Environment variables are automatically _expanded_. This means you can reference previously-defined variables in your environment variables.
+
+```txt .env icon="settings"
+FOO=world
+BAR=hello$FOO
+```
+
+```ts
+process.env.BAR; // => "helloworld"
+```
+
+This is useful for constructing connection strings or other compound values.
+
+```txt .env icon="settings"
+DB_USER=postgres
+DB_PASSWORD=secret
+DB_HOST=localhost
+DB_PORT=5432
+DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME
+```
+
+This can be disabled by escaping the `$` with a backslash.
+
+```txt .env icon="settings"
+FOO=world
+BAR=hello\$FOO
+```
+
+```ts
+process.env.BAR; // => "hello$FOO"
+```
+
+### `dotenv`
+
+Generally speaking, you won't need `dotenv` or `dotenv-expand` anymore, because Bun reads `.env` files automatically.
+
+## Reading environment variables
+
+The current environment variables can be accessed via `process.env`.
+
+```ts
+process.env.API_TOKEN; // => "secret"
+```
+
+Bun also exposes these variables via `Bun.env` and `import.meta.env`, which is a simple alias of `process.env`.
+
+```ts
+Bun.env.API_TOKEN; // => "secret"
+import.meta.env.API_TOKEN; // => "secret"
+```
+
+To print all currently-set environment variables to the command line, run `bun --print process.env`. This is useful for debugging.
+
+```sh
+bun --print process.env
+BAZ=stuff
+FOOBAR=aaaaaa
+<lots more lines>
+```
+
+## TypeScript
+
+In TypeScript, all properties of `process.env` are typed as `string | undefined`.
+
+```ts
+Bun.env.whatever;
+// string | undefined
+```
+
+To get autocompletion and tell TypeScript to treat a variable as a non-optional string, we'll use [interface merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces).
+
+```ts
+declare module "bun" {
+  interface Env {
+    AWESOME: string;
+  }
+}
+```
+
+Add this line to any file in your project. It will globally add the `AWESOME` property to `process.env` and `Bun.env`.
+
+```ts
+process.env.AWESOME; // => string
+```
+
+## Configuring Bun
+
+These environment variables are read by Bun and configure aspects of its behavior.
+
+| Name                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NODE_TLS_REJECT_UNAUTHORIZED`           | `NODE_TLS_REJECT_UNAUTHORIZED=0` disables SSL certificate validation. This is useful for testing and debugging, but you should be very hesitant to use this in production. Note: This environment variable was originally introduced by Node.js and we kept the name for compatibility.                                                                                                                                                                                                                                                                                   |
+| `BUN_CONFIG_VERBOSE_FETCH`               | If `BUN_CONFIG_VERBOSE_FETCH=curl`, then fetch requests will log the url, method, request headers and response headers to the console. This is useful for debugging network requests. This also works with `node:http`. `BUN_CONFIG_VERBOSE_FETCH=1` is equivalent to `BUN_CONFIG_VERBOSE_FETCH=curl` except without the `curl` output.                                                                                                                                                                                                                                   |
+| `BUN_RUNTIME_TRANSPILER_CACHE_PATH`      | The runtime transpiler caches the transpiled output of source files larger than 50 kb. This makes CLIs using Bun load faster. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set, then the runtime transpiler will cache transpiled output to the specified directory. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set to an empty string or the string `"0"`, then the runtime transpiler will not cache transpiled output. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is unset, then the runtime transpiler will cache transpiled output to the platform-specific cache directory. |
+| `TMPDIR`                                 | Bun occasionally requires a directory to store intermediate assets during bundling or other operations. If unset, defaults to the platform-specific temporary directory: `/tmp` on Linux, `/private/tmp` on macOS.                                                                                                                                                                                                                                                                                                                                                        |
+| `NO_COLOR`                               | If `NO_COLOR=1`, then ANSI color output is [disabled](https://no-color.org/).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `FORCE_COLOR`                            | If `FORCE_COLOR=1`, then ANSI color output is force enabled, even if `NO_COLOR` is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `BUN_CONFIG_MAX_HTTP_REQUESTS`           | Control the maximum number of concurrent HTTP requests sent by fetch and `bun install`. Defaults to `256`. If you are running into rate limits or connection issues, you can reduce this number.                                                                                                                                                                                                                                                                                                                                                                          |
+| `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD` | If `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true`, then `bun --watch` will not clear the console on reload                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `DO_NOT_TRACK`                           | Disable uploading crash reports to `bun.report` on crash. On macOS & Windows, crash report uploads are enabled by default. Otherwise, telemetry is not sent yet as of May 21st, 2024, but we are planning to add telemetry in the coming weeks. If `DO_NOT_TRACK=1`, then auto-uploading crash reports and telemetry are both [disabled](https://do-not-track.dev/).                                                                                                                                                                                                      |
+| `BUN_OPTIONS`                            | Prepends command-line arguments to any Bun execution. For example, `BUN_OPTIONS="--hot"` makes `bun run dev` behave like `bun --hot run dev`                                                                                                                                                                                                                                                                                                                                                                                                                              |
+
+## Runtime transpiler caching
+
+For files larger than 50 KB, Bun caches transpiled output into `$BUN_RUNTIME_TRANSPILER_CACHE_PATH` or the platform-specific cache directory. This makes CLIs using Bun load faster.
+
+This transpiler cache is global and shared across all projects. It is safe to delete the cache at any time. It is a content-addressable cache, so it will never contain duplicate entries. It is also safe to delete the cache while a Bun process is running.
+
+It is recommended to disable this cache when using ephemeral filesystems like Docker. Bun's Docker images automatically disable this cache.
+
+### Disable the runtime transpiler cache
+
+To disable the runtime transpiler cache, set `BUN_RUNTIME_TRANSPILER_CACHE_PATH` to an empty string or the string `"0"`.
+
+```sh
+BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
+```
+
+### What does it cache?
+
+It caches:
+
+- The transpiled output of source files larger than 50 KB.
+- The sourcemap for the transpiled output of the file
+
+The file extension `.pile` is used for these cached files.