Environment Variables for AI Coders
Your app needs passwords and secret keys to work. Here's how to manage them safely, no coding knowledge required.
In this chapter
- What environment variables are and why they exist
- Which keys must stay secret and which are safe to expose
- How to set them up locally and on your hosting platform
- How to fix the 'works locally but not in production' issue
What Are Environment Variables?
Think of environment variables as a lockbox of passwords your app needs. Your app might need a password to connect to its database, a key to process payments through Stripe, and another key to use AI features. Instead of writing these directly into your app (dangerous!), you put them in a secure lockbox.
They're called "environment" variables because you can have different lockboxes for different situations. When you're testing on your own computer, the lockbox has test passwords. When your app is live on the internet, it uses a different lockbox with real passwords. Same app, different lockboxes.
What goes in your lockbox (the .env.local file):
- Your database password
- Your Stripe payment key
- Your AI key (OpenAI, Anthropic, etc.)
- Your website address (this one's OK to be public)
The Rules
Which File Does What
Your project can have a few different "lockbox" files. Here's what each one is for:
Common Secrets Your App Might Need
How to Tell Your AI Tool About Secrets
You don't need to write code yourself. Just tell your AI tool what you need. Here are prompts you can copy and paste:
“I need to add a Stripe payment key to my app. Create a .env.local file if one doesn't exist, add the Stripe secret key variable, and make sure .env.local is in .gitignore so it doesn't get uploaded to GitHub.”
“I have a database URL from Supabase (or Neon, PlanetScale, etc.). Add it as an environment variable in my project. It should be a server-only secret, not visible to website visitors.”
“Review my project and make sure no secret keys or passwords are hardcoded in the source code. All secrets should be in .env.local, and .env.local should be in .gitignore. Also check that no secret variables have NEXT_PUBLIC_ in their name.”
“I need to add my website URL as an environment variable that my front-end can access. This isn't a secret, so it should use the NEXT_PUBLIC_ prefix.”
Adding to Vercel
When you deploy to Vercel, your .env.local file doesn't go with it (that's the whole point: it stays on your computer). You need to add your secrets through the Vercel dashboard.
-
1
Go to your project on Vercel Open vercel.com and select your project from the dashboard.
-
2
Navigate to Settings > Environment Variables Click the Settings tab at the top, then select Environment Variables from the left sidebar.
-
3
Add your key and value Type the variable name and paste the value. You can also paste the entire contents of your .env.local file and Vercel will sort it out automatically.
-
4
Select environments Choose which environments get this variable: Production (your live site), Preview (test versions from pull requests), and/or Development. Most variables should be added to all three.
-
5
Redeploy for changes to take effect After adding or changing a variable, you need to redeploy your project. Vercel only reads secrets when it builds your app.
Common Mistakes
Prompt This
Copy-paste these prompts into your AI tool to apply what you just learned.
“Set up environment variables for my Next.js app. I need to store API keys for [Supabase/Stripe/Resend]. Show me the .env.local file and how to access them in my code.”
“My app works locally but breaks in production because of missing environment variables. Help me identify which env vars I need to add to my Vercel dashboard.”
Frequently Asked Questions
Do I need to understand the code that uses environment variables?
No. Your AI tool handles the code. You just need to know what secrets your app needs, and where to put them (your .env.local file and your hosting dashboard like Vercel).
Where do I get these secret keys?
From each service you sign up for. For example, Stripe gives you a payment key in your Stripe dashboard. OpenAI gives you an AI key in your OpenAI account. Each service has a settings or API keys page.
What if I accidentally share a secret publicly?
Change it immediately. Go to the service (Stripe, OpenAI, etc.) and generate a new key. The old one should be deleted or revoked so nobody can use it.
Can I use the same secrets for testing and the real app?
You can, but it's better not to. Most services give you separate "test" keys and "live" keys. Use test keys on your computer and live keys on your deployed website. That way you won't accidentally charge a real credit card while testing.
How many .env files do I need?
For most AI coding projects, just one: .env.local. That's the file on your computer that holds your secrets. When you deploy, you add those same secrets through your hosting dashboard (like Vercel).