Environment Variables and .env Files Explained: Secrets Without the Confusion

Your app needs a database URL. It needs a Stripe secret key. It needs an API key for email or analytics. If you paste those directly into your code, two bad things happen: anyone with access to your code (or your Git history) can see them, and you cannot use different values when you run the app on your laptop versus on the live server.

Environment variables solve both problems. They store secrets and configuration outside your code and let you change them per environment. This guide explains what they are, how to use them, and how to avoid common mistakes.

What Is an Environment Variable?

An environment variable is a named value that your application reads when it runs. The value lives in the environment — a small set of key-value pairs provided by the system or your hosting platform — not in your source code.

For example, instead of writing:

const stripeKey = "sk_live_abc123..."

you write:

const stripeKey = process.env.STRIPE_SECRET_KEY

The actual key is set elsewhere: in a .env file on your machine or in your hosting provider's dashboard. Your code never contains the secret; it only asks for it by name.

Why Use Them?

Security — Secrets do not belong in code. Code gets committed to Git, copied, and sometimes shared. If a key is in the code, it can leak. Environment variables keep secrets out of the repository.

Flexibility — On your laptop you might use a test database and test API keys. On the live server you use the real database and live keys. Same code, different environment variables. You do not have to edit the code when you deploy.

Documentation — A good project has a .env.example file that lists every variable the app needs. New developers (or future you) know exactly what to configure without reading the whole codebase.

The .env File (and Why It Is Ignored by Git)

During development, environment variables are often stored in a file named .env or .env.local. The file looks like this:

DATABASE_URL=postgresql://user:pass@host/dbname
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_APP_URL=http://localhost:3000

Each line is a key, an equals sign, and a value. No quotes unless the value contains spaces. No semicolons.

Critical rule: The .env and .env.local files must be listed in .gitignore. They must never be committed to Git. If they were, anyone with access to the repository would see your secrets. This template (and any sensible project) already ignores them.

.env.example: The Template

Because .env is not in Git, how does someone new to the project know what variables to set? The answer is .env.example.

.env.example is committed to Git. It lists every variable the app needs, with placeholder values or empty values and short comments:

# Database (get this from your Supabase project settings)
DATABASE_URL=

# Stripe (use test keys for development)
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Public URL (used for links in emails, etc.)
NEXT_PUBLIC_APP_URL=http://localhost:3000

To get started, you copy .env.example to .env.local, fill in the real values, and never commit .env.local. The example file is the checklist; the real file stays on your machine (and on the server, in the hosting dashboard).

Where Variables Are Set

• Local development — In .env.local (or .env) in your project folder. The framework (e.g., Next.js) loads these when you run npm run dev.
• Production — In your hosting provider's dashboard (e.g., Vercel). You add the same variable names and production values. The provider injects them when your app runs in production.

So: one set of names, different values per environment. Your code only reads process.env.SOME_KEY; it does not care where the value came from.

The NEXT_PUBLIC_ Prefix (Next.js)

In Next.js, only variables that start with NEXT_PUBLIC_ are visible in the browser. Everything else is server-only.

• Server-only — Use for secrets: database URL, Stripe secret key, API keys. Never use NEXT_PUBLIC_ for these.
• Browser — Use NEXT_PUBLIC_ only for values that must be available in client-side code, and only for non-sensitive data (e.g., NEXT_PUBLIC_APP_URL). Assume anything with NEXT_PUBLIC_ can be seen by users.

If you are not sure, do not add the prefix. You can always expose a non-secret value via an API route or server component instead.

What This Template Expects

This template uses environment variables for Supabase (database and auth), Stripe (payments), and optional features (PWA, MFA, etc.). The full list is in .env.example at the root of the project. Each variable has a comment explaining what it is and where to get the value.

When you set up the project, you copy .env.example to .env.local, fill in the values, and restart the dev server. When you deploy, you add the same variable names (with production values) in your hosting provider's environment settings.

Key Takeaways

• Environment variables store secrets and config outside your code. The app reads them at runtime by name (e.g., process.env.STRIPE_SECRET_KEY).
• Use them for API keys, database URLs, and anything that must stay secret or change per environment.
• .env and .env.local hold real values and must be in .gitignore — never commit them.
• .env.example lists every variable with placeholders and comments; commit it so others know what to set.
• In Next.js, only variables prefixed with NEXT_PUBLIC_ are visible in the browser; use that prefix only for non-sensitive values.