Update environment variable docs.

docs/pages/repo/docs/handbook/_meta.json

@@ -6,7 +6,7 @@
   "dev": "Development Tasks",
   "building-your-app": "Building Your App",
   "deploying-with-docker": "Deploying with Docker",
-  "environment-variables": "Environment Variables",
+  "environment-variables": "Using Environment Variables",
   "sharing-code": "Sharing Code",
   "linting": "Linting",
   "testing": "Testing",

docs/pages/repo/docs/handbook/environment-variables.mdx

@@ -1,54 +1,140 @@
-# Using environment variables
-
-We currently recommend using `dotenv-cli` as the simplest way to bring your environment variables into your development tasks.
-
-We're actively looking forward to improving the developer experience and ergonomics for your environment variables in a future release of Turborepo.
-
-## With local `turbo`
-
-1. Place all of your variables into the root of your monorepo as a `.env` file.
+import Callout from '../../../../components/Callout';
+import { Tabs, Tab } from '../../../../components/Tabs';
+
+# Using Environment Variables
+
+Because environment variables are not captured in source code, they're not as easily shared across machines. To set up environment variables for your repository you will need to take advantage of a number of Turborepo features.
+
+## Working with Next.js and other libraries that load environment variables
+
+If your framework automatically loads environment variables from a particular file, such as `.env`, you must indicate to `turbo` the location of these files. This shows a baseline configuration for Next.js and Vite, who load their environment files themselves:
+
+<Tabs items={['Next.js', 'Vite']} storageKey="selected-framework">
+  <Tab>
+    ```jsonc
+    {
+      "$schema": "https://turbo.build/schema.json",
+      "globalDotEnv": [".env"],
+      "pipeline": {
+        "build": {
+          "dotEnv": [".env.production.local", ".env.local", ".env.production", ".env"]
+        },
+        "dev": {
+          "dotEnv": [".env.development.local", ".env.local", ".env.development", ".env"]
+        },
+        "test": {
+          "dotEnv": [".env.test.local", ".env.test", ".env"]
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab>
+    ```jsonc
+    {
+      "$schema": "https://turbo.build/schema.json",
+      "globalDotEnv": [".env"],
+      "pipeline": {
+        "build": {
+          "dotEnv": [".env.production.local", ".env.production", ".env.local", ".env"]
+        },
+        "dev": {
+          "dotEnv": [".env.development.local", ".env.development", ".env.local", ".env"]
+        },
+        "test": {
+          "dotEnv": [".env.test.local", ".env.test", ".env.local", ".env"]
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Loading Your Own Variables
+
+If you need to load a large number of environment variables into your environment just prior to execution, we recommend using `dotenv-cli`. It's the simplest way to bring your environment variables into your development tasks.
+
+<Callout type="info">
+  Turborepo does not load any `.env` files into the environment! Your task must handle loading of the `.env` files itself.
+</Callout>
+
+### With locally-installed `turbo`
+
+1. Place all of your variables into the root of your monorepo in a `.env` file.
 
 2. Install `dotenv-cli` into the root of your repository.
 
-```json
+```json filename="package.json" highlight=3
 {
-   "devDependencies": {
-+    "dotenv-cli": "latest"
+  "devDependencies": {
+    "dotenv-cli": "latest"
   }
 }
 ```
 
 3. Adjust your scripts to inject the environment variables into the `turbo` command.
 
-```json
+```json filename="package.json" highlight=3
 {
   "scripts": {
     "dev": "dotenv -- turbo dev"
   }
 }
 ```
 
-## With global `turbo`
+4. Add the `.env` file to `turbo.json`:
+
+```json filename="turbo.json" highlight=2
+{
+  "globalDotEnv": [".env"],
+  "pipeline": {
+    "dev": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+### With globally-installed `turbo`
 
-If you're using `turbo` globally, you'll also need to install `dotenv-cli` globally so you can put `dotenv --` in front of the `turbo` command in your terminal.
+If you're using `turbo` globally, you'll also need to install `dotenv-cli` globally so you can put `dotenv --` in front of the `turbo` command in your terminal:
 
-## With workspace scripts
+```sh
+dotenv -- turbo dev
+```
 
-You may prefer to make your workspaces responsible for loading environment variables. This approach is more flexible, if you don't mind the extra configuration overhead in your `package.json` scripts.
+### Advanced Configuration: Per-workspace Environment Variables
+
+You may prefer to make your workspaces responsible for loading their own environment variables. This approach is more flexible and gives better results if you don't mind the extra configuration overhead in your `package.json` scripts.
 
 To use this strategy:
 
-1. Place all of your variables into the root of your monorepo as a `.env` file.
+1. Place your variables into `.env` file(s) in the root of the packages that they needed to be loaded in.
 
 2. Install `dotenv-cli` in the workspace.
 
-```json
+```json filename="app/site/package.json"
 {
   "scripts": {
-+.   "dev": "dotenv -e ../../.env start-server"
-  }
-  "devDependencies": {
-+    "dotenv-cli": "latest"
+    "dev": "dotenv -e .env.development -- start-server",
+    "build": "dotenv -e .env -- bundle-app"
   },
+  "devDependencies": {
+    "dotenv-cli": "latest"
+  }
+}
+```
+
+3. Add the `.env` file(s) to `turbo.json`:
+
+```json filename="turbo.json"
+{
+  "globalDotEnv": [".env"],
+  "pipeline": {
+    "dev": {
+      "dotEnv": [".env.development"],
+      "dependsOn": ["^build"]
+    }
+  }
 }
 ```