---
title: "Environment Variables"
description: "Manage environment variables across development, preview, and production scopes using the Vercel dashboard and vercel env pull."
canonical_url: "https://vercel.com/academy/svelte-on-vercel/environment-variables"
md_url: "https://vercel.com/academy/svelte-on-vercel/environment-variables.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-10-02T17:46:31.254Z"
content_type: "lesson"
course: "svelte-on-vercel"
course_title: "Svelte on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Environment Variables

# Managing Environment Variables on Vercel

The chat feature needs an API key to talk to the AI Gateway. Committing that key exposes it in your Git history. Vercel's environment variables keep secrets out of source control and let you set different values for development, preview, and production.

## Outcome

Configure the `AI_GATEWAY_API_KEY` across Vercel's three environment scopes and pull it locally with `vercel env pull`.

## Fast Track

1. Add `AI_GATEWAY_API_KEY` in the Vercel dashboard under **Settings → Environment Variables**
2. Run `vercel env pull` to sync the variable to your local `.env` file
3. Review its declaration in `src/env.ts` and import it in server code from `$app/env/private`

## Vercel's Three Scopes

Every environment variable on Vercel has one or more scopes:

| Scope           | When it's used                        | Example                           |
| --------------- | ------------------------------------- | --------------------------------- |
| **Production**  | Deployments from your main branch     | Live API key with billing alerts  |
| **Preview**     | Deployments from other branches (PRs) | Shared team key for testing       |
| **Development** | Local dev via `vercel env pull`       | Personal key with low rate limits |

Choose a test API key for preview deployments and a production key for your main branch, or use the same key in all three scopes.

## Hands-on Exercise 1.2

Add the AI Gateway API key to your Vercel project and access it in server code:

**Requirements:**

1. Add `AI_GATEWAY_API_KEY` in the Vercel dashboard with all three scopes enabled
2. Pull the variable locally with `vercel env pull`
3. Confirm `src/env.ts` declares the variable, then access it in server code using `$app/env/private`

**Implementation hints:**

- Get an API key from the [AI Gateway settings](https://vercel.com/~/ai-gateway) in your Vercel dashboard
- The `.env` file is already in `.gitignore`, so never commit it
- SvelteKit 3 declares environment variables in `src/env.ts`. They are private and dynamic by default; server code imports them from `$app/env/private`
- The chat endpoint has a TODO comment showing where this variable will be used. Check `src/routes/api/chat/+server.ts`

## Try It

1. **Add the variable in Vercel:**
   - Go to your project → **Settings** → **Environment Variables**
   - Name: `AI_GATEWAY_API_KEY`
   - Value: your gateway key
   - Check all three scopes: Production, Preview, Development
   - Click **Save**

2. **Pull locally:**

   \*\*Note: First time using vercel env pull?\*\*

   If you haven't connected your local directory to the Vercel project yet, run `vercel link` first. The CLI needs to know which project to pull variables from.

   ```bash
   $ vercel env pull
   Downloading Development Environment Variables for project ski-alerts
   ✅ Created .env file
   ```

3. **Verify the `.env` file exists:**
   ```bash
   $ cat .env
   # Created by Vercel CLI
   AI_GATEWAY_API_KEY="your-gateway-key"
   ```

4. **Check that server code can access it:**

   The chat endpoint in the starter shows the pattern you'll use in Section 2:

   ```typescript title="src/routes/api/chat/+server.ts" {2}
   // You'll implement this in Section 2, but the import pattern is:
   import { AI_GATEWAY_API_KEY } from '$app/env/private';

   // Access directly: AI_GATEWAY_API_KEY
   ```

## Commit

You don't need to change code for this lesson. The environment variable lives in Vercel's dashboard and your local `.env` file (which is gitignored).

## Done-When

- [ ] `AI_GATEWAY_API_KEY` appears in your Vercel project's Environment Variables settings
- [ ] Running `vercel env pull` creates a `.env` file locally
- [ ] The `.env` file contains your API key
- [ ] The `.env` file is listed in `.gitignore`
- [ ] `src/env.ts` declares `AI_GATEWAY_API_KEY` as a private variable

## Solution

**Step 1: Vercel Dashboard**

Navigate to your project → Settings → Environment Variables. Add:

| Key                  | Value              | Scopes                           |
| -------------------- | ------------------ | -------------------------------- |
| `AI_GATEWAY_API_KEY` | `your-gateway-key` | Production, Preview, Development |

**Step 2: Pull locally**

```bash
vercel env pull
```

This creates `.env` in your project root with all Development-scoped variables.

**Step 3: Access in SvelteKit**

The starter declares the key in `src/env.ts`:

```typescript title="src/env.ts"
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
  AI_GATEWAY_API_KEY: { schema: v.optional(v.string(), '') }
});
```

The empty-string default lets the weather dashboard run before you configure AI Gateway. Add a real key before starting the AI lessons. This file declares the variable; the secret value stays in Vercel and your local `.env` file.

Import it in server code:

```typescript title="src/lib/ai/provider.ts"
import { createGateway } from 'ai';
import { AI_GATEWAY_API_KEY } from '$app/env/private';

export const gateway = createGateway({ apiKey: AI_GATEWAY_API_KEY });
```

Variables are dynamic by default. If you need a value inlined at build time, set `static: true` in its declaration. See the [SvelteKit environment variable documentation](https://svelte.dev/docs/kit/environment-variables) for validation and configuration options.

\*\*Warning: Never make secrets public\*\*

Setting `public: true` exposes a variable through `$app/env/public`. Keep API keys private. SvelteKit prevents private environment imports in browser code.

## Troubleshooting

\*\*Warning: .env file is empty after pulling\*\*

Check that you enabled the **Development** scope when you added the variable. Production-only variables won't appear in your local `.env` file.

## Advanced: Per-Scope Values

You can set different values per scope. A common pattern:

- **Development**: A personal API key with low rate limits
- **Preview**: A shared team key for testing
- **Production**: A production key with higher limits and billing alerts

To set scope-specific values, uncheck "All Environments" in the dashboard and add the variable once per scope with different values.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)