docs(vite): explain how to set env vars (nrwl#20790)

docs/shared/guides/use-environment-variables-in-react.md

@@ -11,6 +11,43 @@ You can read more about how to define environment variables in Vite [here](https
 
 You can then use these variables in your application code like so: `import.meta.env.VITE_CUSTOM_VAR`.
 
+### Environment Variable Conflict between Nx and Vite
+
+When using Nx with Vite, you may encounter an issue related to loading environment variables that can lead to unexpected behavior. This issue arises due to the way Nx and Vite handle environment files and configuration settings.
+
+1. **Nx Environment Variable Loading**: Nx loads environment variables from configuration names using the `--configuration` flag. This is the preferred method in Nx, especially when you have a default configuration specified in your `project.json` file for most targets. In our [guide on how to define environment variables](https://nx.dev/recipes/tips-n-tricks/define-environment-variables), you can see that if you're using the `configuration` option, then Nx will load `.env.[configuration-name]` files.
+
+2. **Vite Environment Variable Loading**: Vite loads environment files named `.env.[mode]` using the `--mode` flag.
+
+The conflict occurs when you use the `--configuration` flag in Nx. In such cases, the `--mode` flag in Vite is ignored. For example, this behavior can be particularly confusing, as it may seem like you are always loading the `development` mode in Vite, instead of the expected one, if you're using the `--configuration=development` setting or if your default configuration is `development`.
+
+The root cause of this issue is that Nx has already loaded variables from `.env.[configuration]`. So any variables defined in both Nx and Vite's `.env.[mode]` files will have their values overridden by the Nx-loaded values.
+
+#### Solution
+
+We recommend that developers adapt to the Nx way of handling environment variables and refer to our [documentation on defining environment variables](https://nx.dev/recipes/tips-n-tricks/define-environment-variables). This will help ensure consistent behavior and prevent conflicts when using Nx with Vite.
+
+However, if you still want to use Vite's `mode`, you still can. To ensure seamless integration between Nx and Vite environment variables, you can establish a clear distinction between `configuration` and `mode` names. By assigning distinct names to both `configuration` and `mode`, you can eliminate any potential conflicts that may arise during environment variable loading. Additionally, consider defining custom configurations in your Nx workspace, each with a corresponding `mode` option. For example, you can create configurations like `development`, `production`, and `staging`, each with its respective `mode` set, like this:
+
+```json
+"configurations": {
+  "development": {
+    "mode": "development"
+  },
+  "production": {
+    "mode": "production"
+  },
+  "staging": {
+    "mode": "staging"
+  },
+  "my-other-mode": {
+    "mode": "my-other-mode"
+  }
+}
+```
+
+That way, you can set the `--configuration` flag to `development`, `production`, or `staging` to load the corresponding `.env.[configuration]` file, and this will respect the `mode` set in the configuration.
+
 ### Using environment variables in `index.html`
 
 You cannot interpolate environment variables into your `index.html` file for React applications using Vite.