Why is process.env.MY_VAR undefined in the browser in Next.js?

Next.js only exposes variables to the browser when their names start with NEXT_PUBLIC_. Everything else stays server-side, which protects secrets.

# .env.local
DATABASE_URL=mongodb://localhost:27017/app   # server only
NEXT_PUBLIC_SITE_URL=https://example.com     # also in browser bundle

// client component
const site = process.env.NEXT_PUBLIC_SITE_URL;

Important details

1. NEXT_PUBLIC_* values are inlined at build time. Changing them on the server after next build has no effect; rebuild (this matters in Docker: pass them as build args).
2. Dynamic lookups like process.env[name] are not inlined in the client bundle. Reference the full name literally.
3. Server-side variables are read at runtime in Node for dynamically rendered code, so one Docker image can run with different DATABASE_URL values. Pages that are statically prerendered at build time use the values present during next build.
4. Load order: process.env, .env.$(NODE_ENV).local, .env.local (not in test), .env.$(NODE_ENV), .env.
5. Restart next dev after editing env files.
6. Never commit .env.local; add .env*.local to .gitignore.

Passing a server value to the client safely

Read it in a server component and pass it as a prop:

export default function Page() {
  return <Widget region={process.env.REGION ?? "eu"} />;
}

Validate at startup

import { z } from "zod";
export const env = z.object({
  DATABASE_URL: z.string().url(),
  AUTH_SECRET: z.string().min(32),
}).parse(process.env);

Pitfall: prefixing a secret with NEXT_PUBLIC_ publishes it to everyone. If a key must stay private, call the third-party API from a route handler or server action instead.