How do environment variables work in Next.js?

Question

Accepted Answer

Next.js loads environment variables from `.env` files, with an important security rule: variables are **server-only by default**, and only those prefixed with `NEXT_PUBLIC_` are exposed to the browser.

## The files

```text
.env                # loaded in all environments
.env.local          # local overrides — GITIGNORED (put secrets here)
.env.development    # only in `next dev`
.env.production     # only in production builds
```

## The critical prefix rule

```bash
# .env.local
DATABASE_URL=postgres://...secret...   # server-only — NEVER sent to the browser
NEXT_PUBLIC_API_URL=https://api.example.com  # exposed to the browser
```

```tsx
// Server Component / Route Handler / Server Action — can read anything
const db = process.env.DATABASE_URL;          // ✅ works on the server

// Client Component — only NEXT_PUBLIC_* are available
"use client";
const api = process.env.NEXT_PUBLIC_API_URL;  // ✅ works
const secret = process.env.DATABASE_URL;      // ❌ undefined in the browser
```

This prefix rule is a **security feature**: it prevents you from accidentally shipping database passwords or API secrets to the client. A non-prefixed variable simply doesn't exist in browser bundles.

## How NEXT_PUBLIC values are embedded

```text
NEXT_PUBLIC_* are INLINED at BUILD time (baked into the JS bundle).
```

Because they're inlined at build time, changing a `NEXT_PUBLIC_` value requires a **rebuild** — and you should never put true secrets behind the prefix (they'd be visible in the bundle to anyone).

## Best practices

```text
✓ Secrets (DB URLs, API keys) → no prefix, kept server-side, in .env.local (gitignored)
✓ Public config (public API base, analytics id) → NEXT_PUBLIC_
✓ Commit a .env.example documenting required vars (no real values)
```

## Why it matters

The server-only-by-default model with the `NEXT_PUBLIC_` opt-in is Next.js's guardrail against leaking secrets to the client — a common, serious mistake.

Understanding which variables reach the browser, that public ones are build-time inlined, and where to store secrets (gitignored `.env.local`) is essential for both functionality and security.