Using .env files

You have an API key. Now you need a safe place to put it, somewhere your app can read it but the world can't. That place is a .env file.

What is a .env file?

A .env file is like a locked drawer in your kitchen. Your app knows where it is and can open it. But it never leaves your computer, and it's never shared.

• It's a plain text file that holds environment variables. An environment variable is a named setting your app reads when it starts.
• It keeps secrets separate from your code, so you can share code without sharing keys.
• In Next.js projects, the file is usually called .env.local.

What goes inside

Each line is a name, an equals sign, and a value. No spaces around the =.

# AI assistant
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stripe (test mode)
STRIPE_SECRET_KEY=sk_test_your-key

Let's break this down:

• Names are in CAPITAL_LETTERS with underscores, by convention.
• Lines starting with # are comments. The app ignores them.
• Your app reads a value by its name, so ANTHROPIC_API_KEY must match exactly in the code.

my-app/
├── app/
├── .env.local        ← your real secrets (never shared)
├── .env.example      ← names only, safe to share
├── .gitignore        ← lists .env.local
└── package.json

Keep it out of Git with .gitignore

Soon you'll use Git and GitHub to save and share your code. A .gitignore file is a list of files Git should never save. Your .env files must be on it.

# secrets
.env
.env.local
.env*.local

# installed packages
node_modules

It's also good to keep a .env.example file with the names but no values. It reminds you (and others) which variables the app needs. That one is safe to commit.

The NEXT_PUBLIC_ caveat

In Next.js, any variable whose name starts with NEXT_PUBLIC_ is sent to the browser. That means anyone can see it.

• OK with NEXT_PUBLIC_: the Supabase URL and anon key (with Row Level Security on), the Stripe publishable key.
• Never with NEXT_PUBLIC_: AI API keys, the Supabase service_role key, the Stripe secret key.

Telling AI builders to use env vars

Tools like Claude Code and Lovable are good at this, but only if you ask. Put a rule like this in your prompt or in your project notes:

Security rules for this project:
- Never hard-code API keys or secrets in the code. Read them from environment variables.
- Store local values in .env.local and make sure .gitignore includes .env and .env.local.
- Create a .env.example with every variable name and empty values.
- Only use NEXT_PUBLIC_ for values that are safe for anyone to see.
- If you need a new secret, tell me its name and I'll add the value myself.

Adding env vars on Vercel

Your .env.local file stays on your laptop. It is not uploaded when you deploy. So you must add the same variables to your host.

1. Open your project in the Vercel dashboard.
2. Go to Settings, then Environment Variables.
3. Add each name and value from your .env.local, one at a time.
4. Redeploy the project so the new values are picked up.

Troubleshooting

Common mistakes

• Adding spaces or quotes by accident, like API_KEY = "abc". Use API_KEY=abc.
• Creating .gitignore after the first commit. Set it up before you ever run git add.
• Putting real values in .env.example. It should hold names only.

What's next?

Your secrets are safe. Now let's learn Git, so you can save snapshots of your project and never lose your work again.