The Secret Notebook of Your App: A Beginner's Guide to .env Files in Next.js

If you've ever followed a Next.js tutorial and stumbled across a mysterious line like NEXT_PUBLIC_API_KEY=your_key_here and had no clue what that meant — this post is for you. No jargon, no assumptions. Just a clear, practical explanation so you can move forward with confidence.

First, What Even Is a .env File?

Think of it like a secret notebook. When you build a web app, it needs access to sensitive values — things like passwords, API keys, or database addresses. You could write those values directly inside your code, but that's a big problem: code gets shared. You push it to GitHub, show it to a friend, or post a snippet online — and suddenly your secrets are exposed.

A .env file solves this by keeping those values separate from your code. The file lives on your machine, never gets shared, and your code simply looks up the values by name when it needs them.

Creating Your First .env File

In the root folder of your Next.js project (the main folder, same level as package.json), create a new file called:

.env.local

Notice the dot at the start — that's intentional. Next.js uses .env.local as your main private file during local development.

Inside the file, each line follows this simple format:

MY_SECRET_KEY=abc123supersecret
DATABASE_URL=mongodb://localhost:27017/myapp
NEXT_PUBLIC_SITE_NAME=My Awesome Blog

A few rules to keep in mind:

→ No spaces around the equals sign. Write KEY=value, not KEY = value.
→ Lines starting with # are comments. Next.js ignores them, so you can use them to leave notes for yourself.
→ No quotes needed around values in most cases (unless the value contains spaces — then wrap it in double quotes).

The Most Important Concept: Two Types of Variables

This is where most beginners get tripped up, so pay close attention. In Next.js, there are two kinds of environment variables, and they behave very differently.

1. Server-only variables (no prefix)

DATABASE_PASSWORD=supersecret123
STRIPE_SECRET_KEY=sk_live_abc...

These are private. Next.js only makes them available on the server — in API routes and server-side code. The browser never sees them. This is exactly what you want for anything sensitive.

2. Public variables (NEXT_PUBLIC_ prefix)

NEXT_PUBLIC_SITE_NAME=My Blog
NEXT_PUBLIC_API_URL=https://api.myservice.com

These are visible to everyone — including the browser. Use this prefix when the value is safe to be public, like a site name or a public-facing API URL. Never put passwords or secret tokens here.

💡 The golden rule: if it's a secret → no prefix. If it's safe to be public → add NEXT_PUBLIC_.

How to Use Variables in Your Code

Once a variable is in your .env.local file, you access it anywhere in your code with process.env.YOUR_VARIABLE_NAME.

In server-side code (API routes, server components):

const secretKey = process.env.MY_SECRET_KEY

In browser/client components:

const siteName = process.env.NEXT_PUBLIC_SITE_NAME

⚠️ Common gotcha: If you try to use a server-only variable (no NEXT_PUBLIC_ prefix) inside a browser component, it will come back as undefined — silently, with no error. If you're seeing undefined where a value should be, this is almost always the reason.

The Different .env Files and When to Use Them

Next.js supports several .env file variations. Here's a simple breakdown:

File	When it's used
.env.local	Your local machine only. Never committed to Git. This is your go-to.
.env	Shared defaults for all environments. Safe for non-secret values.
.env.development	Only loaded when running `npm run dev`.
.env.production	Only loaded when running the production build.

For most projects starting out, you only need .env.local. Done.

The Critical Step: Add .env.local to .gitignore

This is non-negotiable. If you're using Git (and you should be), you need to make sure .env.local is never committed to your repository.

Open your .gitignore file and check that this line is there:

.env.local

Good news: Next.js adds this automatically when you create a new project with create-next-app. But it's always worth double-checking before your first commit.

What About Your Teammates (or Deploying to Production)?

Since .env.local never gets shared, your teammates won't have it when they clone the project. The standard solution is to create a .env.example file — a copy of your .env.local but with all the actual values removed:

# .env.example — copy this file to .env.local and fill in the values

MY_SECRET_KEY=
DATABASE_URL=
NEXT_PUBLIC_SITE_NAME=

Commit this file to Git. It tells anyone who works on the project exactly which variables they need, without exposing the actual secrets.

For deploying to production (Vercel, Netlify, etc.), you don't upload a .env file. Instead, you go to your hosting platform's dashboard and add the environment variables directly in their settings panel. The platform injects them securely at build and runtime.

A Quick Recap

✓ A .env file keeps sensitive values out of your code.
✓ Use .env.local for local development — it stays on your machine.
✓ No prefix → server only (private). NEXT_PUBLIC_ prefix → available in the browser too.
✓ Access values in code with process.env.VARIABLE_NAME.
✓ Always have .env.local in your .gitignore.
✓ Share a .env.example with your team so they know what variables are needed.
✓ On production, set variables in your hosting platform's dashboard.

That's really all there is to it. The .env file looks intimidating the first time you see it, but it's one of the simplest and most important habits to build as a developer. Once it clicks, you'll wonder how you ever worked without it.