Beginner5 min readShare
Was this chapter helpful?
Share
Your app needs passwords and secret keys to work. Here's how to manage them safely — no coding knowledge required.
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)
Never upload your secrets to GitHub
Your .env.local file should stay on your computer only. If it ends up on GitHub, anyone in the world can see your passwords. Ask your AI tool to make sure .env files are listed in .gitignore (a file that tells Git what to ignore).
Some values are OK to be public
Variables whose names start with NEXT_PUBLIC_ become visible to anyone who visits your website. Only use this for things that are safe to share, like your website's URL. Never use it for passwords or secret keys.
Secrets stay hidden automatically
Variables without NEXT_PUBLIC_ in the name are kept secret. They only work behind the scenes on the server. Your visitors can never see them. This is where passwords, payment keys, and API keys should go.
Restart after changes
After adding or changing anything in your .env.local file, you need to stop your app and start it again. Your app only reads the lockbox when it starts up.
Your project can have a few different "lockbox" files. Here's what each one is for:
.env.local
The one you'll use mostThis is your personal lockbox. It lives only on your computer and never gets uploaded anywhere. Put all your secrets here. If the same setting exists in other .env files, this one wins.
.env
This is for shared, non-secret settings that everyone working on the project can see. Things like the name of the project or default settings. This file can be uploaded to GitHub safely (as long as it has no passwords).
.env.development / .env.production
These are optional files for more advanced setups. One holds settings for when you're testing, the other for when your app is live. Most AI coders won't need these — .env.local handles everything.
Your database password
Connects your app to the database where all your data lives
Your Stripe payment key
Lets your app accept credit card payments
Your AI key (OpenAI, Anthropic, etc.)
Gives your app access to AI features like chatbots
Your login system secret (Clerk, Auth0)
Keeps your user login system secure
Your website address
Tells your app its own URL — safe for anyone to see
Your login system public ID
The non-secret part of your login system — safe for anyone to see
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."
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.
Go to your project on Vercel
Open vercel.com and select your project from the dashboard.
Navigate to Settings > Environment Variables
Click the Settings tab at the top, then select Environment Variables from the left sidebar.
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.
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.
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.
If you add NEXT_PUBLIC_ to the front of a secret name, it becomes visible to anyone who visits your website. Never do this with passwords, payment keys, or AI keys.
If your .env.local file gets pushed to GitHub, anyone can see your passwords and keys. Tell your AI tool: "Make sure .env files are in .gitignore." If this happens, change all your passwords immediately.
You added a secret to your .env.local file but your app says it's missing. This usually means you need to stop your app and start it again. Secrets are only loaded when the app starts up.
Your .env.local file only exists on your computer. When you deploy to Vercel (or another host), you need to add your secrets there too. See the "Adding to Vercel" section below.
Copy-paste these prompts into your AI tool to apply what you just learned.
SET UP ENV VARIABLES
"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."
FIX MISSING ENV VARS IN PRODUCTION
"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."
