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

package/docs/guides/runtime/build-time-constants.mdx

@@ -0,0 +1,295 @@
+---
+title: Build-time constants with --define
+sidebarTitle: Build-time constants
+mode: center
+---
+
+The `--define` flag can be used with `bun build` and `bun build --compile` to inject build-time constants into your application. This is especially useful for embedding metadata like build versions, timestamps, or configuration flags directly into your compiled executables.
+
+```sh terminal icon="terminal"
+bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/index.ts --outfile myapp
+```
+
+---
+
+## Why use build-time constants?
+
+Build-time constants are embedded directly into your compiled code, making them:
+
+- **Zero runtime overhead** - No environment variable lookups or file reads
+- **Immutable** - Values are baked into the binary at compile time
+- **Optimizable** - Dead code elimination can remove unused branches
+- **Secure** - No external dependencies or configuration files to manage
+
+This is similar to `gcc -D` or `#define` in C/C++, but for JavaScript/TypeScript.
+
+---
+
+## Basic usage
+
+### With `bun build`
+
+```sh terminal icon="terminal"
+# Bundle with build-time constants
+bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist
+```
+
+### With `bun build --compile`
+
+```sh terminal icon="terminal"
+# Compile to executable with build-time constants
+bun build --compile --define BUILD_VERSION='"1.0.0"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
+```
+
+### JavaScript API
+
+```ts build.ts icon="/icons/typescript.svg"
+await Bun.build({
+  entrypoints: ["./src/index.ts"],
+  outdir: "./dist",
+  define: {
+    BUILD_VERSION: '"1.0.0"',
+    BUILD_TIME: '"2024-01-15T10:30:00Z"',
+    DEBUG: "false",
+  },
+});
+```
+
+---
+
+## Common use cases
+
+### Version information
+
+Embed version and build metadata directly into your executable:
+
+<CodeGroup>
+
+```ts src/version.ts icon="/icons/typescript.svg"
+// These constants are replaced at build time
+declare const BUILD_VERSION: string;
+declare const BUILD_TIME: string;
+declare const GIT_COMMIT: string;
+
+export function getVersion() {
+  return {
+    version: BUILD_VERSION,
+    buildTime: BUILD_TIME,
+    commit: GIT_COMMIT,
+  };
+}
+```
+
+```sh Build command
+bun build --compile \
+  --define BUILD_VERSION='"1.2.3"' \
+  --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
+  --define GIT_COMMIT='"abc123"' \
+  src/cli.ts --outfile mycli
+```
+
+</CodeGroup>
+
+### Feature flags
+
+Use build-time constants to enable/disable features:
+
+```ts src/version.ts icon="/icons/typescript.svg"
+// Replaced at build time
+declare const ENABLE_ANALYTICS: boolean;
+declare const ENABLE_DEBUG: boolean;
+
+function trackEvent(event: string) {
+  if (ENABLE_ANALYTICS) {
+    // This entire block is removed if ENABLE_ANALYTICS is false
+    console.log("Tracking:", event);
+  }
+}
+
+if (ENABLE_DEBUG) {
+  console.log("Debug mode enabled");
+}
+```
+
+```sh
+# Production build - analytics enabled, debug disabled
+bun build --compile --define ENABLE_ANALYTICS=true --define ENABLE_DEBUG=false src/app.ts --outfile app-prod
+
+# Development build - both enabled
+bun build --compile --define ENABLE_ANALYTICS=false --define ENABLE_DEBUG=true src/app.ts --outfile app-dev
+```
+
+### Configuration
+
+Replace configuration objects at build time:
+
+```ts src/version.ts icon="/icons/typescript.svg"
+declare const CONFIG: {
+  apiUrl: string;
+  timeout: number;
+  retries: number;
+};
+
+// CONFIG is replaced with the actual object at build time
+const response = await fetch(CONFIG.apiUrl, {
+  timeout: CONFIG.timeout,
+});
+```
+
+```sh
+bun build --compile --define 'CONFIG={"apiUrl":"https://api.example.com","timeout":5000,"retries":3}' src/app.ts --outfile app
+```
+
+---
+
+## Advanced patterns
+
+### Environment-specific builds
+
+Create different executables for different environments:
+
+```json
+{
+  "scripts": {
+    "build:dev": "bun build --compile --define NODE_ENV='\"development\"' --define API_URL='\"http://localhost:3000\"' src/app.ts --outfile app-dev",
+    "build:staging": "bun build --compile --define NODE_ENV='\"staging\"' --define API_URL='\"https://staging.example.com\"' src/app.ts --outfile app-staging",
+    "build:prod": "bun build --compile --define NODE_ENV='\"production\"' --define API_URL='\"https://api.example.com\"' src/app.ts --outfile app-prod"
+  }
+}
+```
+
+### Using shell commands for dynamic values
+
+Generate build-time constants from shell commands:
+
+```sh
+# Use git to get current commit and timestamp
+bun build --compile \
+  --define BUILD_VERSION="\"$(git describe --tags --always)\"" \
+  --define BUILD_TIME="\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" \
+  --define GIT_COMMIT="\"$(git rev-parse HEAD)\"" \
+  src/cli.ts --outfile mycli
+```
+
+### Build automation script
+
+Create a build script that automatically injects build metadata:
+
+```ts
+// build.ts
+import { $ } from "bun";
+
+const version = await $`git describe --tags --always`.text();
+const buildTime = new Date().toISOString();
+const gitCommit = await $`git rev-parse HEAD`.text();
+
+await Bun.build({
+  entrypoints: ["./src/cli.ts"],
+  outdir: "./dist",
+  define: {
+    BUILD_VERSION: JSON.stringify(version.trim()),
+    BUILD_TIME: JSON.stringify(buildTime),
+    GIT_COMMIT: JSON.stringify(gitCommit.trim()),
+  },
+});
+
+console.log(`Built with version ${version.trim()}`);
+```
+
+---
+
+## Important considerations
+
+### Value format
+
+Values must be valid JSON that will be parsed and inlined as JavaScript expressions:
+
+```sh
+# ✅ Strings must be JSON-quoted
+--define VERSION='"1.0.0"'
+
+# ✅ Numbers are JSON literals
+--define PORT=3000
+
+# ✅ Booleans are JSON literals
+--define DEBUG=true
+
+# ✅ Objects and arrays (use single quotes to wrap the JSON)
+--define 'CONFIG={"host":"localhost","port":3000}'
+
+# ✅ Arrays work too
+--define 'FEATURES=["auth","billing","analytics"]'
+
+# ❌ This won't work - missing quotes around string
+--define VERSION=1.0.0
+```
+
+### Property keys
+
+You can use property access patterns as keys, not just simple identifiers:
+
+```sh
+# ✅ Replace process.env.NODE_ENV with "production"
+--define 'process.env.NODE_ENV="production"'
+
+# ✅ Replace process.env.API_KEY with the actual key
+--define 'process.env.API_KEY="abc123"'
+
+# ✅ Replace nested properties
+--define 'window.myApp.version="1.0.0"'
+
+# ✅ Replace array access
+--define 'process.argv[2]="--production"'
+```
+
+This is particularly useful for environment variables:
+
+```ts
+// Before compilation
+if (process.env.NODE_ENV === "production") {
+  console.log("Production mode");
+}
+
+// After compilation with --define 'process.env.NODE_ENV="production"'
+if ("production" === "production") {
+  console.log("Production mode");
+}
+
+// After optimization
+console.log("Production mode");
+```
+
+### TypeScript declarations
+
+For TypeScript projects, declare your constants to avoid type errors:
+
+```ts
+// types/build-constants.d.ts
+declare const BUILD_VERSION: string;
+declare const BUILD_TIME: string;
+declare const NODE_ENV: "development" | "staging" | "production";
+declare const DEBUG: boolean;
+```
+
+### Cross-platform compatibility
+
+When building for multiple platforms, constants work the same way:
+
+```sh
+# Linux
+bun build --compile --target=bun-linux-x64 --define PLATFORM='"linux"' src/app.ts --outfile app-linux
+
+# macOS
+bun build --compile --target=bun-darwin-x64 --define PLATFORM='"darwin"' src/app.ts --outfile app-macos
+
+# Windows
+bun build --compile --target=bun-windows-x64 --define PLATFORM='"windows"' src/app.ts --outfile app-windows.exe
+```
+
+---
+
+## Related
+
+- [Define constants at runtime](/guides/runtime/define-constant) - Using `--define` with `bun run`
+- [Building executables](/bundler/executables) - Complete guide to `bun build --compile`
+- [Bundler API](/bundler) - Full bundler documentation including `define` option

package/docs/guides/runtime/cicd.mdx

@@ -0,0 +1,45 @@
+---
+title: Install and run Bun in GitHub Actions
+sidebarTitle: GitHub Actions
+mode: center
+---
+
+Use the official [`setup-bun`](https://github.com/oven-sh/setup-bun) GitHub Action to install `bun` in your GitHub Actions runner.
+
+```yaml workflow.yml icon="file-code"
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2 // [!code ++]
+
+      # run any `bun` or `bunx` command
+      - run: bun install // [!code ++]
+      - run: bun index.ts // [!code ++]
+      - run: bun run build // [!code ++]
+```
+
+---
+
+To specify a version of Bun to install:
+
+```yaml workflow.yml icon="file-code"
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: oven-sh/setup-bun@v2
+        with: // [!code ++]
+          bun-version: 1.2.0 # or "latest", "canary", <sha> // [!code ++]
+```
+
+---
+
+Refer to the [README.md](https://github.com/oven-sh/setup-bun) for complete documentation of the `setup-bun` GitHub Action.

package/docs/guides/runtime/codesign-macos-executable.mdx

@@ -0,0 +1,61 @@
+---
+title: Codesign a single-file JavaScript executable on macOS
+description: Fix the "can't be opened because it is from an unidentified developer" Gatekeeper warning when running your JavaScript executable.
+sidebarTitle: Codesign on macOS
+mode: center
+---
+
+Compile your executable using the `--compile` flag.
+
+```sh
+bun build --compile ./path/to/entry.ts --outfile myapp
+```
+
+---
+
+List your available signing identities. One of these will be your signing identity that you pass to the `codesign` command. This command requires macOS.
+
+```sh terminal icon="terminal"
+security find-identity -v -p codesigning
+```
+
+```txt
+1. XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX "Developer ID Application: Your Name (ZZZZZZZZZZ)"
+   1 valid identities found
+```
+
+---
+
+Optional, but recommended: create an `entitlements.plist` file with the necessary permissions for the JavaScript engine to work correctly.
+
+```xml entitlements.plist icon="file-code"
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.disable-executable-page-protection</key>
+    <true/>
+    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
+    <true/>
+    <key>com.apple.security.cs.disable-library-validation</key>
+    <true/>
+</dict>
+</plist>
+```
+
+---
+
+Sign your executable using the `codesign` command and verify it works.
+
+```bash terminal icon="terminal"
+codesign --entitlements entitlements.plist -vvvv --deep --sign "XXXXXXXXXX" ./myapp --force
+codesign -vvv --verify ./myapp
+```
+
+---
+
+For more information on macOS codesigning, refer to [Apple's Code Signing documentation](https://developer.apple.com/documentation/security/code_signing_services). For details about creating single-file executables with Bun, see [Standalone Executables](/bundler/executables). This guide requires Bun v1.2.4 or newer.

package/docs/guides/runtime/define-constant.mdx

@@ -0,0 +1,149 @@
+---
+title: Define and replace static globals & constants
+sidebarTitle: Define constants
+mode: center
+---
+
+The `--define` flag lets you declare statically-analyzable constants and globals. It replace all usages of an identifier or property in a JavaScript or TypeScript file with a constant value. This feature is supported at runtime and also in `bun build`. This is sort of similar to `#define` in C/C++, except for JavaScript.
+
+```sh terminal icon="terminal"
+bun --define process.env.NODE_ENV="'production'" src/index.ts # Runtime
+bun build --define process.env.NODE_ENV="'production'" src/index.ts # Build
+```
+
+---
+
+These statically-known values are used by Bun for dead code elimination and other optimizations.
+
+```ts
+if (process.env.NODE_ENV === "production") {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+Before the code reaches the JavaScript engine, Bun replaces `process.env.NODE_ENV` with `"production"`.
+
+```ts
+if ("production" === "production") {
+  // [!code ++]
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+It doesn't stop there. Bun's optimizing transpiler is smart enough to do some basic constant folding.
+
+Since `"production" === "production"` is always `true`, Bun replaces the entire expression with the `true` value.
+
+```ts
+if (true) {
+  // [!code ++]
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+And finally, Bun detects the `else` branch is not reachable, and eliminates it.
+
+```ts
+console.log("Production mode");
+```
+
+---
+
+## What types of values are supported?
+
+Values can be strings, identifiers, properties, or JSON.
+
+### Replace global identifiers
+
+To make all usages of `window` be `undefined`, you can use the following command.
+
+```sh
+bun --define window="undefined" src/index.ts
+```
+
+This can be useful when Server-Side Rendering (SSR) or when you want to make sure that the code doesn't depend on the `window` object.
+
+```js
+if (typeof window !== "undefined") {
+  console.log("Client-side code");
+} else {
+  console.log("Server-side code");
+}
+```
+
+You can also set the value to be another identifier. For example, to make all usages of `global` be `globalThis`, you can use the following command.
+
+```sh
+bun --define global="globalThis" src/index.ts
+```
+
+`global` is a global object in Node.js, but not in web browsers. So, you can use this to fix some cases where the code assumes that `global` is available.
+
+### Replace values with JSON
+
+`--define` can also be used to replace values with JSON objects and arrays.
+
+To replace all usages of `AWS` with the JSON object `{"ACCESS_KEY":"abc","SECRET_KEY":"def"}`, you can use the following command.
+
+```sh
+# JSON
+bun --define AWS='{"ACCESS_KEY":"abc","SECRET_KEY":"def"}' src/index.ts
+```
+
+Those will be transformed into the equivalent JavaScript code.
+
+From:
+
+```ts
+console.log(AWS.ACCESS_KEY); // => "abc"
+```
+
+To:
+
+```ts
+console.log("abc");
+```
+
+### Replace values with other properties
+
+You can also pass properties to the `--define` flag.
+
+For example, to replace all usages of `console.write` with `console.log`, you can use the following command (requires Bun v1.1.5 or later)
+
+```sh
+bun --define console.write=console.log src/index.ts
+```
+
+That transforms the following input:
+
+```ts
+console.write("Hello, world!");
+```
+
+Into the following output:
+
+```ts
+console.log("Hello, world!");
+```
+
+## How is this different than setting a variable?
+
+You can also set `process.env.NODE_ENV` to `"production"` in your code, but that won't help with dead code elimination. In JavaScript, property accesses can have side effects. Getters & setters can be functions, and even dynamically defined (due to prototype chains and Proxy). Even if you set `process.env.NODE_ENV` to `"production"`, on the next line, it is not safe for static analysis tools to assume that `process.env.NODE_ENV`is`"production"`.
+
+## How is this different than find-and-replace or string replacement?
+
+The `--define` flag operates on the AST (Abstract Syntax Tree) level, not on the text level. It happens during the transpilation process, which means it can be used in optimizations like dead code elimination.
+
+String replacement tools tend to have escaping issues and replace unintended parts of the code.

package/docs/guides/runtime/delete-directory.mdx

@@ -0,0 +1,39 @@
+---
+title: Delete directories
+sidebarTitle: Delete directories
+mode: center
+---
+
+To recursively delete a directory and all its contents, use `rm` from `node:fs/promises`. This is like running `rm -rf` in JavaScript.
+
+```ts delete-directory.ts icon="/icons/typescript.svg"
+import { rm } from "node:fs/promises";
+
+// Delete a directory and all its contents
+await rm("path/to/directory", { recursive: true, force: true });
+```
+
+---
+
+These options configure the deletion behavior:
+
+- `recursive: true` - Delete subdirectories and their contents
+- `force: true` - Don't throw errors if the directory doesn't exist
+
+You can also use it without `force` to ensure the directory exists:
+
+```ts delete-directory.ts icon="/icons/typescript.svg"
+try {
+  await rm("path/to/directory", { recursive: true });
+} catch (error) {
+  if (error.code === "ENOENT") {
+    console.log("Directory doesn't exist");
+  } else {
+    throw error;
+  }
+}
+```
+
+---
+
+See [Docs > API > FileSystem](https://bun.com/docs/api/file-io) for more filesystem operations.

package/docs/guides/runtime/delete-file.mdx

@@ -0,0 +1,21 @@
+---
+title: Delete files
+sidebarTitle: Delete files
+mode: center
+---
+
+To delete a file, use `Bun.file(path).delete()`.
+
+```ts delete-file.ts icon="/icons/typescript.svg"
+// Delete a file
+const file = Bun.file("path/to/file.txt");
+await file.delete();
+
+// Now the file doesn't exist
+const exists = await file.exists();
+// => false
+```
+
+---
+
+See [Docs > API > FileSystem](https://bun.com/docs/api/file-io) for more filesystem operations.

package/docs/guides/runtime/heap-snapshot.mdx

@@ -0,0 +1,28 @@
+---
+title: Inspect memory usage using V8 heap snapshots
+sidebarTitle: Heap snapshots
+mode: center
+---
+
+Bun implements V8's heap snapshot API, which allows you to create snapshots of the heap at runtime. This helps debug memory leaks in your JavaScript/TypeScript application.
+
+```ts snapshot.ts icon="/icons/typescript.svg"
+import v8 from "node:v8";
+
+// Creates a heap snapshot file with an auto-generated name
+const snapshotPath = v8.writeHeapSnapshot();
+console.log(`Heap snapshot written to: ${snapshotPath}`);
+```
+
+---
+
+## Inspect memory in Chrome DevTools
+
+To view V8 heap snapshots in Chrome DevTools:
+
+1. Open Chrome DevTools (F12 or right-click and select "Inspect")
+2. Go to the "Memory" tab
+3. Click the "Load" button (folder icon)
+4. Select your `.heapsnapshot` file
+
+<Frame>![Chrome DevTools Memory Tab](/images/chrome-devtools-memory.png)</Frame>

package/docs/guides/runtime/import-html.mdx

@@ -0,0 +1,17 @@
+---
+title: Import a HTML file as text
+sidebarTitle: Import HTML
+mode: center
+---
+
+To import a `.html` file in Bun as a text file, use the `type: "text"` attribute in the import statement.
+
+```ts file.ts icon="/icons/typescript.svg"
+import html from "./file.html" with { type: "text" };
+
+console.log(html); // <!DOCTYPE html><html><head>...
+```
+
+This can also be used with hot module reloading and/or watch mode to force Bun to reload whenever the `./file.html` file changes.
+
+This feature was added in Bun v1.1.5.