Skip to content

carapace-sh/carapace-bin / skills/bun

Use when working with the bun CLI — Bun's all-in-one JavaScript runtime and toolkit. Covers the CLI command reference (install, add, remove, run, build, test, x, create, init, pm, upgrade, link, unlink), bunfig.toml configuration, environment variables, the package manager and lockfile, the test runner, the bundler, the Bun runtime API (Bun.serve, Bun.file, Bun.spawn, Bun.write, hashing, transpiler), the Bun shell ($ template literal), module resolution and loaders, and globals. Triggers on: "bun", "bunx", "bun install", "bun add", "bun remove", "bun run", "bun build", "bun test", "bun x", "bun create", "bun init", "bun pm", "bun upgrade", "bun link", "bun unlink", "bunfig.toml", "bun.lock", "Bun.serve", "Bun.file", "Bun.write", "Bun.spawn", "Bun.hash", "Bun.password", "bun:test", "Bun.build", "Bun.Transpiler", "bun shell", "$ template", "import.meta", "JavaScriptCore", "Bun.serve", "HTMLRewriter", "Bun.SQL", "Bun.RedisClient", "Bun.Glob", "Bun.plugin", "bun:ffi".

FileKindSize
SKILL.mdskill md8.9 KB
references/bundler.mdmarkdown12.1 KB
references/cli.mdmarkdown15.6 KB
references/config.mdmarkdown11.1 KB
references/environment.mdmarkdown4.5 KB
references/package-manager.mdmarkdown11.1 KB
references/runtime.mdmarkdown15.5 KB
references/shell.mdmarkdown7.5 KB
references/test-runner.mdmarkdown9.7 KB

references/environment.md

View on GitHub
# Bun Environment Variables

Reference for environment variables recognized by Bun, `.env` file handling, and environment-related configuration.

> **Source of truth**: <https://bun.sh/docs/runtime/bunfig> and <https://bun.sh/docs/runtime/env>. For bunfig.toml configuration, see [config.md](config.md).

## Environment Variables Recognized by Bun

| Variable | Related Setting | Description |
|----------|----------------|-------------|
| `DO_NOT_TRACK` | `telemetry` | Disables analytics/telemetry (same as `telemetry = false` in bunfig.toml) |
| `BUN_PORT` | `serve.port` | Default port for `Bun.serve` |
| `PORT` | `serve.port` | Alternative env var for `Bun.serve` port |
| `BUN_INSTALL_GLOBAL_DIR` | `install.globalDir` | Directory for globally installed packages |
| `BUN_INSTALL_BIN` | `install.globalBinDir` | Directory where globally-installed package bins are linked |
| `BUN_INSTALL_GLOBAL_STORE` | `install.globalStore` | Enable/configure global virtual store |
| `BUN_FEATURE_FLAG_NO_ORPHANS` | `run.noOrphans` | Enable no-orphans mode (set to `=1`) |
| `NODE_ENV` | | Standard Node.js env var, affects bundler `--production` flag |
| `CLAUDECODE` | test runner | When set to `1`, quiet output for Claude Code (failure details only) |
| `REPL_ID` | test runner | When set to `1`, quiet output for Replit |
| `AGENT` | test runner | When set to `1`, generic AI agent flag for quiet test output |
| `GITHUB_TOKEN` | `bun create` | Access private repos and avoid rate limits (alias: `GITHUB_ACCESS_TOKEN`) |
| `GITHUB_API_DOMAIN` | `bun create` | GitHub domain for downloads (GitHub Enterprise/proxy) |
| `npm_token` | `install.scopes` | Referenced via `$npm_token` in scope registry config |
| `npm_password` | `install.scopes` | Referenced via `$npm_password` in scope registry config |

## `.env` File Handling

### Automatic Loading

Bun loads `.env` files by default when running files, scripts, or tests. This behavior can be configured:

```toml
# bunfig.toml
env = false              # disable automatic .env loading
```

```toml
[env]
file = false             # alternative syntax
```

### Explicit `.env` File Loading

Use the `--env-file` flag to load environment variables from specific file(s):

```bash
bun --env-file .env.production run index.ts
bun --env-file .env --env-file .env.local run index.ts
```

Files passed with `--env-file` are loaded even when automatic `.env` loading is disabled.

### `.env` File Resolution Order

Bun loads `.env` files in this order (later files override earlier ones):

1. `.env`
2. `.env.local` (or `.env.<NODE_ENV>.local`)
3. `.env.development` / `.env.production` / `.env.test` (based on `NODE_ENV`)

## `Bun.env`

`Bun.env` is an alias for `process.env`. It provides access to all environment variables:

```ts
console.log(Bun.env.HOME);
console.log(Bun.env.NODE_ENV);
```

## Environment Variables in `install.scopes`

In `bunfig.toml`, the `[install.scopes]` section supports referencing environment variables with `$variable` notation:

```toml
[install.scopes]
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }
```

This allows keeping secrets out of the config file and in environment variables instead.

## Environment Variables in Bundling

The `Bun.build()` API and `bun build` CLI support environment variable injection:

```bash
# Inline all process.env.* references as string literals
bun build ./index.tsx --outdir ./out --env inline

# Only inline matching prefix
bun build ./index.tsx --outdir ./out --env "FOO_PUBLIC_*"
```

```ts
await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  env: "inline",           // or "disable", or "FOO_PUBLIC_*"
});
```

## Environment Variables in the Bun Shell

The `$` template literal tag respects environment variables:

```ts
import { $ } from "bun";

// Inline env vars (like bash)
await $`FOO=foo some-command`;

// String interpolation (escaped by default)
const val = "456";
await $`FOO=${val} some-command`;

// Per-command environment
await $`some-command`.env({ ...process.env, FOO: "bar" });

// Global default environment
$.env({ FOO: "bar" });
```

## XDG Config Home

The global `.bunfig.toml` file is searched at:

1. `$HOME/.bunfig.toml`
2. `$XDG_CONFIG_HOME/.bunfig.toml`

If `XDG_CONFIG_HOME` is set, it takes precedence over `$HOME` for the global config file location.

## References

- <https://bun.sh/docs/runtime/bunfig>
- <https://bun.sh/docs/runtime/env>
- <https://bun.sh/docs/runtime/shell>
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall