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 filename="package.json" highlight=3
{
  "devDependencies": {
    "dotenv-cli": "latest"
  }
}
```

3. Adjust your scripts to inject the environment variables into the `turbo` command.

```json filename="package.json" highlight=3
{
  "scripts": {
    "dev": "dotenv -- turbo dev"
  }
}
```

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:

```sh
dotenv -- turbo dev
```

### 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 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 filename="app/site/package.json"
{
  "scripts": {
    "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"]
    }
  }
}
```
