Rework bunfig docs

6 files changed, 517 insertions, 209 deletions

diff --git a/docs/nav.ts b/docs/nav.ts
index 08f6cee44..8ad7646b7 100644
--- a/docs/nav.ts
+++ b/docs/nav.ts
@@ -104,6 +104,9 @@ export default {
     // page("runtime/apis", "APIs", {
     //   description: `Bun is a new JavaScript runtime designed to be a faster, leaner, more modern replacement for Node.js.`,
     // }),
+    page("runtime/env", "Environment variables", {
+      description: `How to read and set environment variables, plus how to use them to configure Bun`,
+    }),
     page("runtime/bun-apis", "Bun APIs", {
       description: `Bun provides a set of highly optimized native APIs for performing common tasks.`,
     }),
@@ -132,7 +135,7 @@ export default {
     page("runtime/autoimport", "Auto-install", {
       description: `Never use node_modules again. Bun can optionally auto-install your dependencies on the fly.`,
     }),
-    page("runtime/configuration", "Configuration", {
+    page("runtime/bunfig", "bunfig.toml", {
       description: `Bun's runtime is configurable with environment variables and the bunfig.toml config file.`,
     }),
     page("runtime/debugger", "Debugger", {
diff --git a/docs/runtime/bunfig.md b/docs/runtime/bunfig.md
new file mode 100644
index 000000000..34e3cfa33
--- /dev/null
+++ b/docs/runtime/bunfig.md
@@ -0,0 +1,416 @@
+Bun's behavior can be configured using its configuration file, `bunfig.toml`.
+
+In general, Bun relies on pre-existing configuration files like `package.json` and `tsconfig.json` to configure its behavior. `bunfig.toml` is only necessary for configuring Bun-specific things. This file is optional, and Bun will work out of the box without it.
+
+## Global vs. local
+
+In general, it's recommended to add a `bunfig.toml` file to your project root, alongside your `package.json`.
+
+To configure Bun globally, you can also create a `.bunfig.toml` file at one of the following paths:
+
+- `$HOME/.bunfig.toml`
+- `$XDG_CONFIG_HOME/.bunfig.toml`
+
+If both a global and local `bunfig` are detected, the results are shallow-merged, with local overriding global. CLI flags will override `bunfig` setting where applicable.
+
+## Runtime
+
+Bun's runtime behavior is configured using top-level fields in the `bunfig.toml` file.
+
+### `preload`
+
+An array of scripts to execute before running a file or script. This is useful for registering plugins.
+
+```toml
+# scripts to run before `bun run`ning a file or script
+# useful for registering plugins
+preload = ["./preload.ts"]
+```
+
+### `jsx`
+
+Configure how Bun handles JSX. You can also set these fields in the `compilerOptions` of your `tsconfig.json`, but they are supported here as well for non-TypeScript projects.
+
+```toml
+jsx = "react"
+jsxFactory = "h"
+jsxFragment = "Fragment"
+jsxImportSource = "react"
+```
+
+Refer to the tsconfig docs for more information on these fields.
+
+- [jsx](https://www.typescriptlang.org/tsconfig#jsx)
+- [jsxFactory](https://www.typescriptlang.org/tsconfig#jsxFactory)
+- [jsxFragment](https://www.typescriptlang.org/tsconfig#jsxFragment)
+- [jsxImportSource](https://www.typescriptlang.org/tsconfig#jsxImportSource)
+
+### `smol`
+
+Enable `smol` mode. This reduces memory usage at the cost of performance.
+
+```toml
+# Reduce memory usage at the cost of performance
+smol = true
+```
+
+### `logLevel`
+
+Set the log level. This can be one of `"debug"`, `"warn"`, or `"error"`.
+
+```toml
+logLevel = "debug" # "debug" | "warn" | "error"
+```
+
+### `define`
+
+The `define` field allows you to replace certain global identifiers with constant expressions. Bun will replace any usage of the identifier with the expression. The expression should be a JSON string.
+
+```toml
+[define]
+# Replace any usage of "process.env.bagel" with the string `lox`.
+# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
+# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
+"process.env.bagel" = "'lox'"
+```
+
+### `loader`
+
+Configure how Bun maps file extensions to loaders. This is useful for loading files that aren't natively supported by Bun. If
+
+```toml
+[loader]
+# when a .bagel file is imported, treat it like a tsx file
+".bagel" = "tsx"
+```
+
+Bun supports the following loaders:
+
+- `jsx`
+- `js`
+- `ts`
+- `tsx`
+- `css`
+- `file`
+- `json`
+- `toml`
+- `wasm`
+- `napi`
+- `base64`
+- `dataurl`
+- `text`
+
+## Test runner
+
+The test runner is configured under the `[test]` section of your bunfig.toml.
+
+```toml
+[test]
+# configuration goes here
+```
+
+### `test.root`
+
+The root directory to run tests from. Default `.`.
+
+```toml
+[test]
+root = "./__tests__"
+```
+
+### `test.preload`
+
+Same as the top-level `preload` field, but only applies to `bun test`.
+
+```toml
+[test]
+preload = ["./setup.ts"]
+```
+
+### `test.smol`
+
+Same as the top-level `smol` field, but only applies to `bun test`.
+
+```toml
+[test]
+smol = true
+```
+
+### `test.coverage`
+
+Enables coverage reporting. Default `false`. Use `--coverage` to override.
+
+```toml
+[test]
+coverage = false
+```
+
+### `test.coverageThreshold`
+
+To specify a coverage threshold. By default, no threshold is set. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
+
+```toml
+[test]
+
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+```
+
+Different thresholds can be specified for line-wise, function-wise, and statement-wise coverage.
+
+```toml
+coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }
+```
+
+### `test.coverageSkipTestFiles`
+
+Whether to skip test files when computing coverage statistics. Default `false`.
+
+```toml
+[test]
+coverageSkipTestFiles = false
+```
+
+## Package manager
+
+Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured under the `[install]` section.
+
+```toml
+[install]
+# configuration here
+```
+
+### `install.optional`
+
+Whether to install optional dependencies. Default `true`.
+
+```toml
+[install]
+optional = true
+```
+
+### `install.dev`
+
+Whether to install development dependencies. Default `true`.
+
+```toml
+[install]
+dev = true
+```
+
+### `install.peer`
+
+Whether to install peer dependencies. Default `false`.
+
+```toml
+[install]
+peer = false
+```
+
+### `install.production`
+
+Whether `bun install` will run in "production mode". Default `false`.
+
+In production mode, `"devDependencies"` are not installed. You can use `--production` in the CLI to override this setting.
+
+```toml
+[install]
+production = false
+```
+
+### `install.exact`
+
+Whether to set an exact version in `package.json`. Default `false`.
+
+By default Bun uses caret ranges; if the `latest` version of a package is `2.4.1`, the version range in your `package.json` will be `^2.4.1`. This indicates that any version from `2.4.1` up to (but not including) `3.0.0` is acceptable.
+
+```toml
+[install]
+exact = false
+```
+
+<!--
+### `install.prefer`
+
+Whether the package manager should prefer offline or online dependency resolution. Default `"online"`.
+
+```toml
+[install]
+prefer = "online"
+```
+
+Valid values are:
+
+{% table %}
+
+---
+
+- `"online"`
+- Prefer online resolution. This is the default. If a package is not found in the local cache, it will be downloaded from the registry.
+
+---
+
+- `"offline"`
+- Prefer offline resolution. When possible, packages will be installed from the global cache. This minimizes the fraction of the time Bun will check for newer versions from the registry. If a package is not found in the global cache, it will be downloaded from the registry.
+
+{% /table %} -->
+
+### `install.auto`
+
+To configure Bun's package auto-install behavior. Default `"auto"` — when no `node_modules` folder is found, Bun will automatically install dependencies on the fly during execution.
+
+```toml
+[install]
+auto = "auto"
+```
+
+Valid values are:
+
+{% table %}
+
+---
+
+- `"auto"`
+- Resolve modules from local `node_modules` if it exists. Otherwise, auto-install dependencies on the fly.
+
+---
+
+- `"force"`
+- Always auto-install dependencies, even if `node_modules` exists
+
+---
+
+- `"disable"`
+- Never auto-install dependencies
+
+---
+
+- `"fallback"`
+- Check local `node_modules` first, the auto-install any packages that aren't found. You can enable this from the CLI with `bun -i`.
+
+{% /table %}
+
+### `install.frozenLockfile`
+
+When true, `bun install` will not update `bun.lockb`. Default `false`. If `package.json` and the existing `bun.lockb` are not in agreement, this will error.
+
+```toml
+[install]
+frozenLockfile = false
+```
+
+### `install.dryRun`
+
+Whether to install optional dependencies. Default `false`. When true, it's equivalent to setting `--dry-run` on all `bun install` commands.
+
+```toml
+[install]
+dryRun = false
+```
+
+### `install.registry`
+
+The default registry is `https://registry.npmjs.org/`. This can be globally configured in `bunfig.toml`:
+
+```toml
+[install]
+# set default registry as a string
+registry = "https://registry.npmjs.org"
+# set a token
+registry = { url = "https://registry.npmjs.org", token = "123456" }
+# set a username/password
+registry = "https://username:password@registry.npmjs.org"
+```
+
+### `install.scopes`
+
+To configure a registry for a particular scope (e.g. `@myorg/<package>`) use `install.scopes`. You can reference environment variables with `$variable` notation.
+
+```toml
+[install.scopes]
+# registry as string
+myorg = "https://username:password@registry.myorg.com/"
+
+# registry with username/password
+# you can reference environment variables
+myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }
+
+# registry with token
+myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+### `install.globalDir`
+
+To configure the directory where Bun puts globally installed packages.
+
+```toml
+[install]
+# where `bun install --global` installs packages
+globalDir = "~/.bun/install/global"
+```
+
+### `install.globalBinDir`
+
+To configure the directory where Bun installs globally installed binaries and CLIs.
+
+```toml
+# where globally-installed package bins are linked
+globalBinDir = "~/.bun/bin"
+```
+
+### `install.cache`
+
+To configure the cache behavior:
+
+```toml
+[install.cache]
+
+# the directory to use for the cache
+dir = "~/.bun/install/cache"
+
+# when true, don't load from the global cache.
+# Bun may still write to node_modules/.cache
+disable = false
+
+# when true, always resolve the latest versions from the registry
+disableManifest = false
+```
+
+### `install.lockfile`
+
+To configure lockfile behavior, use the `install.lockfile` section.
+
+Whether to generate a lockfile on `bun install`. Default `true`.
+
+```toml
+[install.lockfile]
+save = true
+```
+
+Whether to generate a non-Bun lockfile alongside `bun.lockb`. (A `bun.lockb` will always be created.) Currently `"yarn"` is the only supported value.
+
+```toml
+print = "yarn"
+```
+
+<!-- ## Debugging -->
+
+<!--
+```toml
+[debug]
+# When navigating to a blob: or src: link, open the file in your editor
+# If not, it tries $EDITOR or $VISUAL
+# If that still fails, it will try Visual Studio Code, then Sublime Text, then a few others
+# This is used by Bun.openInEditor()
+editor = "code"
+
+# List of editors:
+# - "subl", "sublime"
+# - "vscode", "code"
+# - "textmate", "mate"
+# - "idea"
+# - "webstorm"
+# - "nvim", "neovim"
+# - "vim","vi"
+# - "emacs"
+``` -->
diff --git a/docs/runtime/configuration.md b/docs/runtime/configuration.md
deleted file mode 100644
index d7a1d386d..000000000
--- a/docs/runtime/configuration.md
+++ /dev/null
@@ -1,206 +0,0 @@
-There are two primary mechanisms for configuring the behavior of Bun.
-
-- environment variables
-- `bunfig.toml`: Bun's configuration file
-
-Configuring with `bunfig.toml` is optional. Bun aims to be zero-configuration out of the box, but is also highly configurable for advanced use cases. Your `bunfig.toml` should live in your project root alongside `package.json`.
-
-You can also create a global configuration file at the following paths:
-
-- `$HOME/.bunfig.toml`
-- `$XDG_CONFIG_HOME/.bunfig.toml`
-
-If both a global and local `bunfig` are detected, the results are shallow-merged, with local overriding global. CLI flags will override `bunfig` setting where applicable.
-
-## `bunfig.toml`
-
-### Runtime
-
-```toml
-# scripts to run before `bun run`ning a file or script
-# useful for registering plugins
-preload = ["./preload.ts"]
-
-# equivalent to corresponding tsconfig compilerOptions
-jsx = "react"
-jsxFactory = "h"
-jsxFragment = "Fragment"
-jsxImportSource = "react"
-
-# Reduce memory usage at the cost of performance
-smol = true
-
-# Set Bun's log level
-logLevel = "debug" # "debug", "warn", "error"
-
-[define]
-# Replace any usage of "process.env.bagel" with the string `lox`.
-# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
-# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
-"process.env.bagel" = "'lox'"
-
-[loader]
-# When loading a .bagel file, run the JS parser
-".bagel" = "js"
-```
-
-### Test runner
-
-```toml
-[test]
-# Scripts to run before all test files
-preload = ["./setup.ts"]
-
-# Reduce memory usage at the cost of performance
-smol = true
-```
-
-### Package manager
-
-Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured in [`bunfig.toml`](/docs/runtime/configuration).
-
-### Default flags
-
-The following settings modify the core behavior of Bun's package management commands. **The default values are shown below.**
-
-```toml
-[install]
-
-# whether to install optionalDependencies
-optional = true
-
-# whether to install devDependencies
-dev = true
-
-# whether to install peerDependencies
-peer = false
-
-# equivalent to `--production` flag
-production = false
-
-# equivalent to `--frozen-lockfile` flag
-frozenLockfile = false
-
-# equivalent to `--dry-run` flag
-dryRun = false
-```
-
-### Private scopes and registries
-
-The default registry is `https://registry.npmjs.org/`. This can be globally configured in `bunfig.toml`:
-
-```toml
-[install]
-# set default registry as a string
-registry = "https://registry.npmjs.org"
-# set a token
-registry = { url = "https://registry.npmjs.org", token = "123456" }
-# set a username/password
-registry = "https://username:password@registry.npmjs.org"
-```
-
-To configure scoped registries:
-
-```toml
-[install.scopes]
-# registry as string
-myorg1 = "https://username:password@registry.myorg.com/"
-
-# registry with username/password
-# you can reference environment variables
-myorg12 = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" }
-
-# registry with token
-myorg3 = { token = "$npm_token", url = "https://registry.myorg.com/" }
-```
-
-### Cache
-
-To configure caching behavior:
-
-```toml
-[install]
-# where `bun install --global` installs packages
-globalDir = "~/.bun/install/global"
-
-# where globally-installed package bins are linked
-globalBinDir = "~/.bun/bin"
-
-[install.cache]
-# the directory to use for the cache
-dir = "~/.bun/install/cache"
-
-# when true, don't load from the global cache.
-# Bun may still write to node_modules/.cache
-disable = false
-
-# when true, always resolve the latest versions from the registry
-disableManifest = false
-```
-
-### Lockfile
-
-To configure lockfile behavior:
-
-```toml
-[install.lockfile]
-
-# path to read bun.lockb from
-path = "bun.lockb"
-
-# whether to save a non-Bun lockfile alongside bun.lockb
-# only "yarn" is supported
-print = "yarn"
-```
-
-### Debugging
-
-```toml
-[debug]
-# When navigating to a blob: or src: link, open the file in your editor
-# If not, it tries $EDITOR or $VISUAL
-# If that still fails, it will try Visual Studio Code, then Sublime Text, then a few others
-# This is used by Bun.openInEditor()
-editor = "code"
-
-# List of editors:
-# - "subl", "sublime"
-# - "vscode", "code"
-# - "textmate", "mate"
-# - "idea"
-# - "webstorm"
-# - "nvim", "neovim"
-# - "vim","vi"
-# - "emacs"
-```
-
-## Environment variables
-
-These environment variables are checked by Bun to detect functionality and toggle features.
-
-{% table %}
-
-- Name
-- Description
-
----
-
-- `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.
-
----
-
-- `DO_NOT_TRACK`
-- If `DO_NOT_TRACK=1`, then analytics are [disabled](https://do-not-track.dev/). Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it's not a lot of data.
-
-{% /table %}
diff --git a/docs/runtime/env.md b/docs/runtime/env.md
new file mode 100644
index 000000000..9c6789a95
--- /dev/null
+++ b/docs/runtime/env.md
@@ -0,0 +1,80 @@
+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` or `.env.development` (depending on value of `NODE_ENV`)
+- `.env.local`
+
+```txt#.env
+FOO=hello
+BAR=world
+```
+
+Variables can also be set via the command line.
+
+```sh
+$ FOO=helloworld bun run dev
+```
+
+Or programmatically by assigning a property to `process.env`.
+
+```ts
+process.env.FOO = "hello";
+```
+
+## 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`, which is a simple alias of `process.env`.
+
+```ts
+Bun.env.API_TOKEN; // => "secret"
+```
+
+To print all currently-set environment variables to the command line, run `bun run env`. This is useful for debugging.
+
+```sh
+$ bun run env
+BAZ=stuff
+FOOBAR=aaaaaa
+<lots more lines>
+```
+
+## Configuring Bun
+
+These environment variables are read by Bun and configure aspects of its behavior.
+
+{% table %}
+
+- Name
+- Description
+
+---
+
+- `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.
+
+---
+
+- `DO_NOT_TRACK`
+- If `DO_NOT_TRACK=1`, then analytics are [disabled](https://do-not-track.dev/). Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it's not a lot of data.
+
+{% /table %}
diff --git a/src/bunfig.zig b/src/bunfig.zig
index 02825d2b5..76f33cb82 100644
--- a/src/bunfig.zig
+++ b/src/bunfig.zig
@@ -392,6 +392,18 @@ pub const Bunfig = struct {
                                 install.save_lockfile = value;
                             }
                         }
+
+                        if (lockfile_expr.get("path")) |lockfile| {
+                            if (lockfile.asString(allocator)) |value| {
+                                install.lockfile_path = value;
+                            }
+                        }
+
+                        if (lockfile_expr.get("savePath")) |lockfile| {
+                            if (lockfile.asString(allocator)) |value| {
+                                install.save_lockfile_path = value;
+                            }
+                        }
                     }
 
                     if (_bun.get("optional")) |optional| {
diff --git a/src/resolver/resolver.zig b/src/resolver/resolver.zig
index 8440c3c51..fd6ba9d09 100644
--- a/src/resolver/resolver.zig
+++ b/src/resolver/resolver.zig
@@ -539,7 +539,7 @@ pub const Resolver = struct {
 
     pub fn getPackageManager(this: *Resolver) *PackageManager {
         return this.package_manager orelse brk: {
-            bun.HTTPThread.init() catch unreachable;
+            bun.HTTPThead.init() catch unreachable;
             const pm = PackageManager.initWithRuntime(
                 this.log,
                 this.opts.install,
@@ -3886,7 +3886,10 @@ pub const Resolver = struct {
                         var ts_dir_name = Dirname.dirname(current.abs_path);
                         // not sure why this needs cwd but we'll just pass in the dir of the tsconfig...
                         var abs_path = ResolvePath.joinAbsStringBuf(ts_dir_name, bufs(.tsconfig_path_abs), &[_]string{ ts_dir_name, current.extends }, .auto);
-                        var parent_config_maybe = r.parseTSConfig(abs_path, 0) catch {
+                        var parent_config_maybe = r.parseTSConfig(abs_path, 0) catch |err| {
+                            r.log.addWarningFmt(null, logger.Loc.Empty, r.allocator, "{s} loading tsconfig.json extends {}", .{ @errorName(err), strings.QuotedFormatter{
+                                .text = abs_path,
+                            } }) catch {};
                             break;
                         };
                         if (parent_config_maybe) |parent_config| {