bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/runtime/debugger.mdx

@@ -0,0 +1,335 @@
+---
+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
+
+```typescript icon="/icons/typescript.svg" title="server.ts"
+Bun.serve({
+  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 icon="terminal" title="terminal"
+bun --inspect server.ts
+```
+
+```txt id="terminal"
+------------------ Bun Inspector ------------------
+Listening at:
+  ws://localhost:6499/0tqxs9exrgrm
+
+Inspect in browser:
+  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
+------------------ Bun Inspector ------------------
+```
+
+### `--inspect-brk`
+
+The `--inspect-brk` flag behaves identically to `--inspect`, except it automatically injects a breakpoint at the first line of the executed script. This is useful for debugging scripts that run quickly and exit immediately.
+
+### `--inspect-wait`
+
+The `--inspect-wait` flag behaves identically to `--inspect`, except the code will not execute until a debugger has attached to the running process.
+
+### Setting a port or URL for the debugger
+
+Regardless of which flag you use, you can optionally specify a port number, URL prefix, or both.
+
+```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.
+
+### `debug.bun.sh`
+
+Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's [Web Inspector Interface](https://webkit.org/web-inspector/web-inspector-interface/), which will look familiar to Safari users.
+
+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.
+
+<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.
+
+<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.
+
+<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.
+
+<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.
+
+<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.
+
+<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.
+
+<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.
+
+| Value   | Description                        |
+| ------- | ---------------------------------- |
+| `curl`  | Print requests as `curl` commands. |
+| `true`  | Print request & response info      |
+| `false` | Don't print anything. Default      |
+
+### 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`. This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
+
+```ts index.ts icon="/icons/typescript.svg"
+process.env.BUN_CONFIG_VERBOSE_FETCH = "curl";
+
+await fetch("https://example.com", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ 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.1
+[fetch] > Accept: */*
+[fetch] > Host: example.com
+[fetch] > Accept-Encoding: gzip, deflate, br
+[fetch] > Content-Length: 13
+
+[fetch] < 200 OK
+[fetch] < Accept-Ranges: bytes
+[fetch] < Cache-Control: max-age=604800
+[fetch] < Content-Type: text/html; charset=UTF-8
+[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
+[fetch] < Etag: "3147526947"
+[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
+[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+[fetch] < Server: EOS (vny/044F)
+[fetch] < Content-Length: 1256
+```
+
+The lines with `[fetch] >` are the request from your local code, and the lines with `[fetch] <` are the response from the remote server.
+
+The `BUN_CONFIG_VERBOSE_FETCH` environment variable is supported in both `fetch()` and `node:http` requests, so it should just work.
+
+To print without the `curl` command, set `BUN_CONFIG_VERBOSE_FETCH` to `true`.
+
+```ts index.ts icon="/icons/typescript.svg"
+process.env.BUN_CONFIG_VERBOSE_FETCH = "true";
+
+await fetch("https://example.com", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ foo: "bar" }),
+});
+```
+
+```txt
+[fetch] > HTTP/1.1 POST https://example.com/
+[fetch] > content-type: application/json
+[fetch] > Connection: keep-alive
+[fetch] > User-Agent: Bun/1.3.1
+[fetch] > Accept: */*
+[fetch] > Host: example.com
+[fetch] > Accept-Encoding: gzip, deflate, br
+[fetch] > Content-Length: 13
+
+[fetch] < 200 OK
+[fetch] < Accept-Ranges: bytes
+[fetch] < Cache-Control: max-age=604800
+[fetch] < Content-Type: text/html; charset=UTF-8
+[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
+[fetch] < Etag: "3147526947"
+[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
+[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
+[fetch] < Server: EOS (vny/044F)
+[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.
+
+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
+
+To help with debugging, Bun automatically prints a small source-code preview when an unhandled exception or rejection occurs. You can simulate this behavior by calling `Bun.inspect(error)`:
+
+```ts
+// Create an error
+const err = new Error("Something went wrong");
+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.
+
+```ts icon="file-code"
+1 | // Create an error
+2 | const err = new Error("Something went wrong");
+                ^
+error: Something went wrong
+      at file.js:2:13
+```
+
+### V8 Stack Traces
+
+Bun uses JavaScriptCore as it's engine, but much of the Node.js ecosystem & npm expects V8. JavaScript engines differ in `error.stack` formatting. Bun intends to be a drop-in replacement for Node.js, and that means it's our job to make sure that even though the engine is different, the stack traces are as similar as possible.
+
+That's why when you log `error.stack` in Bun, the formatting of `error.stack` is the same as in Node.js's V8 engine. This is especially useful when you're using libraries that expect V8 stack traces.
+
+#### V8 Stack Trace API
+
+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`
+
+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.
+
+```ts
+Error.prepareStackTrace = (err, stack) => {
+  return stack.map(callSite => {
+    return callSite.getFileName();
+  });
+};
+
+const err = new Error("Something went wrong");
+console.log(err.stack);
+// [ "error.js" ]
+```
+
+The `CallSite` object has the following methods:
+
+| Method                     | Returns                                               |
+| -------------------------- | ----------------------------------------------------- |
+| `getThis`                  | `this` value of the function call                     |
+| `getTypeName`              | typeof `this`                                         |
+| `getFunction`              | function object                                       |
+| `getFunctionName`          | function name as a string                             |
+| `getMethodName`            | method name as a string                               |
+| `getFileName`              | file name or URL                                      |
+| `getLineNumber`            | line number                                           |
+| `getColumnNumber`          | column number                                         |
+| `getEvalOrigin`            | `undefined`                                           |
+| `getScriptNameOrSourceURL` | source URL                                            |
+| `isToplevel`               | returns `true` if the function is in the global scope |
+| `isEval`                   | returns `true` if the function is an `eval` call      |
+| `isNative`                 | returns `true` if the function is native              |
+| `isConstructor`            | returns `true` if the function is a constructor       |
+| `isAsync`                  | returns `true` if the function is `async`             |
+| `isPromiseAll`             | Not implemented yet.                                  |
+| `getPromiseIndex`          | Not implemented yet.                                  |
+| `toString`                 | returns a string representation of the call site      |
+
+In some cases, the `Function` object may have already been garbage collected, so some of these methods may return `undefined`.
+
+##### `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.
+
+This can be helpful when you have callbacks or asynchronous code that makes it difficult to determine where an error originated. The 2nd argument to `Error.captureStackTrace` is the function where you want the stack trace to start.
+
+For example, the below code will make `err.stack` point to the code calling `fn()`, even though the error was thrown at `myInner`.
+
+```ts index.ts icon="/icons/typescript.svg"
+const fn = () => {
+  function myInner() {
+    throw err;
+  }
+
+  try {
+    myInner();
+  } catch (err) {
+    console.log(err.stack);
+    console.log("");
+    console.log("-- captureStackTrace --");
+    console.log("");
+    Error.captureStackTrace(err, fn);
+    console.log(err.stack);
+  }
+};
+
+fn();
+```
+
+```txt
+Error: here!
+    at myInner (file.js:4:15)
+    at fn (file.js:8:5)
+    at module code (file.js:17:1)
+    at moduleEvaluation (native)
+    at moduleEvaluation (native)
+    at <anonymous> (native)
+
+-- captureStackTrace --
+
+Error: here!
+    at module code (file.js:17:1)
+    at moduleEvaluation (native)
+    at moduleEvaluation (native)
+    at <anonymous> (native)
+```

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.