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:

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 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:

   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.

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

3. Verify the .env file exists:

   $ 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:

   src/routes/api/chat/+server.ts

   // 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:

Step 2: Pull locally

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:

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:

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 for validation and configuration options.

Troubleshooting

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.