[PR #70] [MERGED] fix(dotenv): load .env files with Next.js precedence #288

New issue

Closed

opened 2026-05-06 12:38:59 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 12:38:59 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/70
Author: @southpolesteve
Created: 2/25/2026
Status: ✅ Merged
Merged: 2/25/2026
Merged by: @southpolesteve

Base: main ← Head: fix/dotenv-review-fixes

📝 Commits (3)

63c1ba8 feat(cli): load .env files with Next.js precedence
6b5590f fix(dotenv): address review feedback on .env loading
e900128 test(dotenv): add cross-file expansion and multi-line value tests

📊 Changes

6 files changed (+461 additions, -1 deletions)

View changed files

📝 AGENTS.md (+17 -0)
📝 README.md (+30 -1)
📝 packages/vinext/src/cli.ts (+16 -0)
➕ packages/vinext/src/config/dotenv.ts (+132 -0)
📝 packages/vinext/src/deploy.ts (+2 -0)
➕ tests/dotenv.test.ts (+264 -0)

📄 Description

Summary

Closes #24. Supersedes #46 (takes over @liuxiaopai-ai's work and addresses review feedback).

Adds automatic .env file loading with Next.js-compatible precedence for all CLI commands (dev, build, start, deploy).

Load order (highest priority first)

Existing process.env values (shell/CI)
.env.<mode>.local
.env.local (skipped in test mode)
.env.<mode>
.env

Security model

No change to client exposure — only NEXT_PUBLIC_* vars are inlined into client bundles via Vite's define (the existing getNextPublicEnvDefines() mechanism). Non-public vars stay server-only.
The next.config.js env property still bypasses the prefix filter (matches Next.js behavior).
Variable expansion ($VAR / ${VAR}) supported with cycle detection.

Changes from PR #46

Documented Vite interaction — added JSDoc explaining why double-loading is safe (vinext populates process.env for server-side access; Vite populates import.meta.env.VITE_* for its own system)
Fixed escaped dollar sign bug — \$100 was not being unescaped because $ followed by a digit doesn't match the variable-name regex
Added type cast for parseEnv return value
Expanded test coverage from 3 to 13 tests: loadedEnv assertions, production mode precedence, ${VAR} expansion syntax, escaped dollars, circular references, missing files, empty result, getDotenvFiles for all modes
Added AGENTS.md guideline — "Prefer Node.js Built-in APIs" section (uses node:util parseEnv rather than dotenv package)

Co-authored-by: liuxiaopai-ai liuxiaopai-ai@users.noreply.github.com

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/70 **Author:** [@southpolesteve](https://github.com/southpolesteve) **Created:** 2/25/2026 **Status:** ✅ Merged **Merged:** 2/25/2026 **Merged by:** [@southpolesteve](https://github.com/southpolesteve) **Base:** `main` ← **Head:** `fix/dotenv-review-fixes` --- ### 📝 Commits (3) - [`63c1ba8`](https://github.com/cloudflare/vinext/commit/63c1ba8b937d8df0619a7230aff524c6fa821bb0) feat(cli): load .env files with Next.js precedence - [`6b5590f`](https://github.com/cloudflare/vinext/commit/6b5590f75fbe0c9e02f175d26c732d554a20c781) fix(dotenv): address review feedback on .env loading - [`e900128`](https://github.com/cloudflare/vinext/commit/e900128ec05fe0ff5b504b2434c73a5dfeb75901) test(dotenv): add cross-file expansion and multi-line value tests ### 📊 Changes **6 files changed** (+461 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+17 -0) 📝 `README.md` (+30 -1) 📝 `packages/vinext/src/cli.ts` (+16 -0) ➕ `packages/vinext/src/config/dotenv.ts` (+132 -0) 📝 `packages/vinext/src/deploy.ts` (+2 -0) ➕ `tests/dotenv.test.ts` (+264 -0) </details> ### 📄 Description ## Summary Closes #24. Supersedes #46 (takes over @liuxiaopai-ai's work and addresses review feedback). Adds automatic `.env` file loading with Next.js-compatible precedence for all CLI commands (`dev`, `build`, `start`, `deploy`). ### Load order (highest priority first) 1. Existing `process.env` values (shell/CI) 2. `.env.<mode>.local` 3. `.env.local` (skipped in `test` mode) 4. `.env.<mode>` 5. `.env` ### Security model - **No change to client exposure** — only `NEXT_PUBLIC_*` vars are inlined into client bundles via Vite's `define` (the existing `getNextPublicEnvDefines()` mechanism). Non-public vars stay server-only. - The `next.config.js` `env` property still bypasses the prefix filter (matches Next.js behavior). - Variable expansion (`$VAR` / `${VAR}`) supported with cycle detection. ### Changes from PR #46 - **Documented Vite interaction** — added JSDoc explaining why double-loading is safe (vinext populates `process.env` for server-side access; Vite populates `import.meta.env.VITE_*` for its own system) - **Fixed escaped dollar sign bug** — `\$100` was not being unescaped because `$` followed by a digit doesn't match the variable-name regex - **Added type cast** for `parseEnv` return value - **Expanded test coverage** from 3 to 13 tests: `loadedEnv` assertions, production mode precedence, `${VAR}` expansion syntax, escaped dollars, circular references, missing files, empty result, `getDotenvFiles` for all modes - **Added AGENTS.md guideline** — "Prefer Node.js Built-in APIs" section (uses `node:util` `parseEnv` rather than `dotenv` package) Co-authored-by: liuxiaopai-ai <liuxiaopai-ai@users.noreply.github.com> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>