From 0300150324cb69c709b03f957c53e0765ac66bd2 Mon Sep 17 00:00:00 2001
From: robobun <robobun@oven.sh>
Date: Tue, 23 Dec 2025 15:31:12 -0800
Subject: [PATCH] docs: fix incorrect [env] section documentation in
 bunfig.toml (#25634)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
- Fixed documentation that incorrectly claimed you could use `[env]` as
a TOML section to set environment variables directly
- The `env` option in bunfig.toml only controls whether automatic `.env`
file loading is disabled (via `env = false`)
- Updated to show the correct approaches: using preload scripts or
`.env` files with `--env-file`

## Test plan
- Documentation-only change, no code changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
---
 docs/runtime/bunfig.mdx     | 20 ++++++++++++++++++++
 docs/test/configuration.mdx | 25 ++++++++++---------------
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/docs/runtime/bunfig.mdx b/docs/runtime/bunfig.mdx
index 2ed368d9ba..a4258d8377 100644
--- a/docs/runtime/bunfig.mdx
+++ b/docs/runtime/bunfig.mdx
@@ -115,6 +115,26 @@ Currently we do not collect telemetry and this setting is only used for enabling
 telemetry = false
 ```
 
+### `env`
+
+Configure automatic `.env` file loading. By default, Bun automatically loads `.env` files. To disable this behavior:
+
+```toml title="bunfig.toml" icon="settings"
+# Disable automatic .env file loading
+env = false
+```
+
+You can also use object syntax with the `file` property:
+
+```toml title="bunfig.toml" icon="settings"
+[env]
+file = false
+```
+
+This is useful in production environments or CI/CD pipelines where you want to rely solely on system environment variables.
+
+Note: Explicitly provided environment files via `--env-file` will still be loaded even when default loading is disabled.
+
 ### `console`
 
 Configure console output behavior.
diff --git a/docs/test/configuration.mdx b/docs/test/configuration.mdx
index 9fff440301..8a8406c6d0 100644
--- a/docs/test/configuration.mdx
+++ b/docs/test/configuration.mdx
@@ -376,16 +376,18 @@ timeout = 10000
 
 ## Environment Variables
 
-You can also set environment variables in your configuration that affect test behavior:
+Environment variables for tests should be set using `.env` files. Bun automatically loads `.env` files from your project root. For test-specific variables, create a `.env.test` file:
 
-```toml title="bunfig.toml" icon="settings"
-[env]
-NODE_ENV = "test"
-DATABASE_URL = "postgresql://localhost:5432/test_db"
-LOG_LEVEL = "error"
+```ini title=".env.test" icon="settings"
+NODE_ENV=test
+DATABASE_URL=postgresql://localhost:5432/test_db
+LOG_LEVEL=error
+```
 
-[test]
-coverage = true
+Then load it with `--env-file`:
+
+```bash terminal icon="terminal"
+bun test --env-file=.env.test
 ```
 
 ## Complete Configuration Example
@@ -398,13 +400,6 @@ Here's a comprehensive example showing all available test configuration options:
 registry = "https://registry.npmjs.org/"
 exact = true
 
-[env]
-# Environment variables for tests
-NODE_ENV = "test"
-DATABASE_URL = "postgresql://localhost:5432/test_db"
-API_URL = "http://localhost:3001"
-LOG_LEVEL = "error"
-
 [test]
 # Test discovery
 root = "src"