fix: allow expanding env vars in reverse order (#19352)

Author: sapphi-red

docs/guide/env-and-mode.md

@@ -77,6 +77,23 @@ If you want to customize the env variables prefix, see the [envPrefix](/config/s
 - Since any variables exposed to your Vite source code will end up in your client bundle, `VITE_*` variables should _not_ contain any sensitive information.
   :::
 
+::: details Expanding variables in reverse order
+
+Vite supports expanding variables in reverse order.
+For example, the `.env` below will be evaluated as `VITE_FOO=foobar`, `VITE_BAR=bar`.
+
+```[.env]
+VITE_FOO=foo${VITE_BAR}
+VITE_BAR=bar
+```
+
+This does not work in shell scripts and other tools like `docker-compose`.
+That said, Vite supports this behavior as this has been supported by `dotenv-expand` for a long time and other tools in JavaScript ecosystem uses older versions that supports this behavior.
+
+To avoid interop issues, it is recommended to avoid relying on this behavior. Vite may start emitting warnings for this behavior in the future.
+
+:::
+
 ### IntelliSense for TypeScript
 
 By default, Vite provides type definitions for `import.meta.env` in [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/client.d.ts). While you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript IntelliSense for user-defined env variables that are prefixed with `VITE_`.

docs/guide/migration.md

@@ -99,8 +99,8 @@ There are other breaking changes which only affect few users.
   - This PR not only introduces a breaking change mentioned above as "Default value for `resolve.conditions`", but also makes `resolve.mainFields` to not be used for no-externalized dependencies in SSR. If you were using `resolve.mainFields` and want to apply that to no-externalized dependencies in SSR, you can use [`ssr.resolve.mainFields`](/config/ssr-options#ssr-resolve-mainfields).
 - [[#18493] refactor!: remove fs.cachedChecks option](https://github.com/vitejs/vite/pull/18493)
   - This opt-in optimization was removed due to edge cases when writing a file in a cached folder and immediately importing it.
-- [[#18697] fix(deps)!: update dependency dotenv-expand to v12](https://github.com/vitejs/vite/pull/18697)
-  - Variables used in interpolation should be declared before the interpolation now. For more details, see [the `dotenv-expand` changelog](https://github.com/motdotla/dotenv-expand/blob/v12.0.1/CHANGELOG.md#1200-2024-11-16).
+- ~~[[#18697] fix(deps)!: update dependency dotenv-expand to v12](https://github.com/vitejs/vite/pull/18697)~~
+  - ~~Variables used in interpolation should be declared before the interpolation now. For more details, see [the `dotenv-expand` changelog](https://github.com/motdotla/dotenv-expand/blob/v12.0.1/CHANGELOG.md#1200-2024-11-16).~~ This breaking change was reverted in v6.1.0.
 - [[#16471] feat: v6 - Environment API](https://github.com/vitejs/vite/pull/16471)
 
   - Updates to an SSR-only module no longer triggers a full page reload in the client. To return to the previous behaviour, a custom Vite plugin can be used:

package.json

@@ -103,7 +103,8 @@
     "patchedDependencies": {
       "[email protected]": "patches/[email protected]",
       "[email protected]": "patches/[email protected]",
-      "[email protected]": "patches/[email protected]"
+      "[email protected]": "patches/[email protected]",
+      "[email protected]": "patches/[email protected]"
     },
     "peerDependencyRules": {
       "allowedVersions": {

packages/vite/src/node/__tests__/env.spec.ts

@@ -39,6 +39,17 @@ describe('loadEnv', () => {
       `)
   })
 
+  test('override 2', () => {
+    expect(loadEnv('development2', join(__dirname, './env')))
+      .toMatchInlineSnapshot(`
+        {
+          "VITE_APP_BASE_ROUTE": "source",
+          "VITE_APP_BASE_URL": "source",
+          "VITE_SOURCE": "source",
+        }
+      `)
+  })
+
   test('VITE_USER_NODE_ENV', () => {
     loadEnv('development', join(__dirname, './env'))
     expect(process.env.VITE_USER_NODE_ENV).toEqual(undefined)

packages/vite/src/node/__tests__/env/.env.development2

@@ -0,0 +1,2 @@
+VITE_SOURCE=source
+VITE_APP_BASE_ROUTE=$VITE_SOURCE

patches/[email protected]

@@ -0,0 +1,31 @@
+diff --git a/lib/main.js b/lib/main.js
+index 794f3bf512ee8cd24fe20e83d159bf8682fb901e..5567e6e282d65b87deea02f8cb396d3e7276581e 100644
+--- a/lib/main.js
++++ b/lib/main.js
+@@ -64,7 +64,7 @@ function expandValue (value, processEnv, runningParsed) {
+ 
+ function expand (options) {
+   // for use with progressive expansion
+-  const runningParsed = {}
++  // const runningParsed = {}
+ 
+   let processEnv = process.env
+   if (options && options.processEnv != null) {
+@@ -79,13 +79,15 @@ function expand (options) {
+     if (processEnv[key] && processEnv[key] !== value) {
+       value = processEnv[key]
+     } else {
+-      value = expandValue(value, processEnv, runningParsed)
++      // PATCH: we pass options.parsed instead of runningParsed
++      //        to allow variables declared in other files to be used
++      value = expandValue(value, processEnv, options.parsed)
+     }
+ 
+     options.parsed[key] = _resolveEscapeSequences(value)
+ 
+     // for use with progressive expansion
+-    runningParsed[key] = _resolveEscapeSequences(value)
++    // runningParsed[key] = _resolveEscapeSequences(value)
+   }
+ 
+   for (const processKey in options.parsed) {