From 37bce389a0cfed5901d5601df971764b4e6c776e Mon Sep 17 00:00:00 2001
From: robobun <robobun@oven.sh>
Date: Thu, 27 Nov 2025 22:51:11 -0800
Subject: [PATCH] docs: document inlining process.env.* values in static HTML
 bundling (#25084)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- Add documentation for the `env` option that inlines `process.env.*`
values in frontend code when bundling HTML files
- Document runtime configuration via `bunfig.toml` `[serve.static]`
section for `bun ./index.html`
- Document production build configuration via CLI (`--env=PUBLIC_*`) and
`Bun.build` API (`env: "PUBLIC_*"`)
- Explain prefix filtering to avoid exposing sensitive environment
variables

## Test plan

- [x] Verify documentation renders correctly in local preview
- [x] Cross-reference with existing `env` documentation in
bundler/index.mdx

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

---------

Co-authored-by: Michael H <git@riskymh.dev>
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
---
 docs/bundler/fullstack.mdx   | 22 +++++++++
 docs/bundler/html-static.mdx | 87 ++++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+)

diff --git a/docs/bundler/fullstack.mdx b/docs/bundler/fullstack.mdx
index 6b108d9866..c28241d8ba 100644
--- a/docs/bundler/fullstack.mdx
+++ b/docs/bundler/fullstack.mdx
@@ -492,6 +492,28 @@ Bun will lazily resolve and load each plugin and use them to bundle your routes.
   the CLI.
 </Note>
 
+## Inline Environment Variables
+
+Bun can replace `process.env.*` references in your frontend JavaScript and TypeScript with their actual values at build time. Configure the `env` option in your `bunfig.toml`:
+
+```toml title="bunfig.toml" icon="settings"
+[serve.static]
+env = "PUBLIC_*"  # only inline env vars starting with PUBLIC_ (recommended)
+# env = "inline"  # inline all environment variables
+# env = "disable" # disable env var replacement (default)
+```
+
+<Note>
+  This only works with literal `process.env.FOO` references, not `import.meta.env` or indirect access like `const env =
+  process.env; env.FOO`.
+
+If an environment variable is not set, you may see runtime errors like `ReferenceError: process
+  is not defined` in the browser.
+
+</Note>
+
+See the [HTML & static sites documentation](/bundler/html-static#inline-environment-variables) for more details on build-time configuration and examples.
+
 ## How It Works
 
 Bun uses `HTMLRewriter` to scan for `<script>` and `<link>` tags in HTML files, uses them as entrypoints for Bun's bundler, generates an optimized bundle for the JavaScript/TypeScript/TSX/JSX and CSS files, and serves the result.
diff --git a/docs/bundler/html-static.mdx b/docs/bundler/html-static.mdx
index 644720688c..125e619b63 100644
--- a/docs/bundler/html-static.mdx
+++ b/docs/bundler/html-static.mdx
@@ -262,6 +262,93 @@ Then, reference TailwindCSS in your HTML via `<link>` tag, `@import` in CSS, or
 
 <Info>Only one of those are necessary, not all three.</Info>
 
+## Inline environment variables
+
+Bun can replace `process.env.*` references in your JavaScript and TypeScript with their actual values at build time. This is useful for injecting configuration like API URLs or feature flags into your frontend code.
+
+### Dev server (runtime)
+
+To inline environment variables when using `bun ./index.html`, configure the `env` option in your `bunfig.toml`:
+
+```toml title="bunfig.toml" icon="settings"
+[serve.static]
+env = "PUBLIC_*"  # only inline env vars starting with PUBLIC_ (recommended)
+# env = "inline"  # inline all environment variables
+# env = "disable" # disable env var replacement (default)
+```
+
+<Note>
+  This only works with literal `process.env.FOO` references, not `import.meta.env` or indirect access like `const env =
+  process.env; env.FOO`.
+
+If an environment variable is not set, you may see runtime errors like `ReferenceError: process
+  is not defined` in the browser.
+
+</Note>
+
+Then run the dev server:
+
+```bash terminal icon="terminal"
+PUBLIC_API_URL=https://api.example.com bun ./index.html
+```
+
+### Build for production
+
+When building static HTML for production, use the `env` option to inline environment variables:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    # Inline all environment variables
+    bun build ./index.html --outdir=dist --env=inline
+
+    # Only inline env vars with a specific prefix (recommended)
+    bun build ./index.html --outdir=dist --env=PUBLIC_*
+    ```
+
+  </Tab>
+  <Tab title="API">
+    ```ts title="build.ts" icon="/icons/typescript.svg"
+    // Inline all environment variables
+    await Bun.build({
+      entrypoints: ["./index.html"],
+      outdir: "./dist",
+      env: "inline", // [!code highlight]
+    });
+
+    // Only inline env vars with a specific prefix (recommended)
+    await Bun.build({
+      entrypoints: ["./index.html"],
+      outdir: "./dist",
+      env: "PUBLIC_*", // [!code highlight]
+    });
+    ```
+
+  </Tab>
+</Tabs>
+
+### Example
+
+Given this source file:
+
+```ts title="app.ts" icon="/icons/typescript.svg"
+const apiUrl = process.env.PUBLIC_API_URL;
+console.log(`API URL: ${apiUrl}`);
+```
+
+And running with `PUBLIC_API_URL=https://api.example.com`:
+
+```bash terminal icon="terminal"
+PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*
+```
+
+The bundled output will contain:
+
+```js title="dist/app.js" icon="/icons/javascript.svg"
+const apiUrl = "https://api.example.com";
+console.log(`API URL: ${apiUrl}`);
+```
+
 ## Echo console logs from browser to terminal
 
 Bun's dev server supports streaming console logs from the browser to the terminal.