Skip to content

src: support override option in process.loadEnvFile#4

Closed
Han5991 wants to merge 1 commit intomainfrom
claude/fix-nodejs-issue-63027-khg50
Closed

src: support override option in process.loadEnvFile#4
Han5991 wants to merge 1 commit intomainfrom
claude/fix-nodejs-issue-63027-khg50

Conversation

@Han5991
Copy link
Copy Markdown
Owner

@Han5991 Han5991 commented May 7, 2026

Summary

Addresses nodejs/node#63027. Adds an opt-in override option to process.loadEnvFile() and a matching --env-file-override-local CLI flag, so callers can switch env-file contexts (integration tests, monorepo env swapping) within one process lifetime.

process.loadEnvFile('.env.test', { override: true });
node --env-file=.env --env-file-override-local index.js

Default behavior — existing env vars take precedence — is unchanged (the contract from nodejs/node#49424).

Based on prior work

nodejs/node#52531 by @IlyasShabi already designed and got 3 approvals for this exact API but stalled with merge conflicts. This branch:

  • rebases the design onto current main (SetEnvironment returns Maybe<void>, BufferValue + ToNamespacedPath for path handling, lazy getValidatedPath)
  • adds validateBoolean for options.override
  • safely detects the loadEnvFile({ override: true }) overload (excludes URL and ArrayBufferView from the options-only branch)
  • adds 7 test cases including CLI flag interaction and validation errors
  • docs use console-style comments to demonstrate the behavior (per @aduh95's feedback in src: add support to override local env variables option nodejs/node#52531) while keeping the existing cjs/mjs example style

Co-authored-by: Ilyas Shabi is set on the commit.

Files changed

  • src/node_dotenv.{h,cc}SetEnvironment(env, override)
  • src/node_options.{h,cc}--env-file-override-local
  • src/node.cc — pass override flag at startup
  • src/node_process_methods.cc — accept override boolean from JS
  • lib/internal/process/per_thread.js — options handling, overload detection
  • test/parallel/test-process-load-env-file.js — 7 new cases
  • doc/api/{cli,process}.md

Test plan

  • python3 tools/test.py --mode=release parallel/test-process-load-env-file
  • make lint-js lint-cpp lint-md
  • make test-only (full JS suite)
  • manual: BASIC=local out/Release/node --env-file=test/fixtures/dotenv/valid.env --env-file-override-local -p 'process.env.BASIC'

Build is currently running in background; verification still pending.

Refs

@Han5991 Han5991 force-pushed the claude/fix-nodejs-issue-63027-khg50 branch 5 times, most recently from 32e7b5e to eac86f7 Compare May 8, 2026 02:29
Add an opt-in `override` option to `process.loadEnvFile()` and a
matching `--env-file-override-local` CLI flag, allowing values from
`.env` files to replace existing variables in `process.env`.

By default, existing environment variables continue to take
precedence; callers must opt in explicitly. This lets a single
process swap env-file contexts at runtime (integration tests,
monorepo configurations) without manually parsing files via
`util.parseEnv()`.
@Han5991 Han5991 force-pushed the claude/fix-nodejs-issue-63027-khg50 branch from eac86f7 to 045dc55 Compare May 8, 2026 02:45
@Han5991
Copy link
Copy Markdown
Owner Author

Han5991 commented May 8, 2026

@claude

@Han5991 Han5991 closed this May 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants