Frontend Beauty
ESC

Type to search the knowledge base.

Environment Variables in Next

Next.js env vars: server-only secrets, NEXT_PUBLIC_ exposure, .env files, and build-time inlining pitfalls.

beginner3 min read
  • nextjs
  • environment-variables

Environment variables configure secrets and environment-specific URLs. Next splits server-only vars from public ones that are embedded into the client bundle.

Docs: Environment Variables.

Naming rules

# server only — available in Server Components, Route Handlers, Actions
DATABASE_URL=postgres://...
AUTH_SECRET=...

# exposed to the browser — NEVER put secrets here
NEXT_PUBLIC_API_BASE=https://api.example.com

Any var without NEXT_PUBLIC_ is not available in Client Components. That is intentional.

Files

.env                # all environments defaults
.env.local          # local secrets (gitignored)
.env.development
.env.production

.env.local overrides. Do not commit secrets.

Usage

// server
const url = process.env.DATABASE_URL;

// client — must be NEXT_PUBLIC_
const base = process.env.NEXT_PUBLIC_API_BASE;

Public vars are inlined at build time for the client. Changing them requires a rebuild/redeploy of that bundle.

Runtime vs build

On Vercel and similar, configure env in the project settings per environment. Edge Middleware only sees vars available to that runtime.

Footguns

Mistake Result
Secret in NEXT_PUBLIC_ Leaked to every browser
Reading server env in client component undefined
Assuming runtime change without rebuild Client still has old public values
Logging env objects Secret leakage in logs

Interview out-loud

“Server secrets stay in non-public env vars used only on the server. NEXT_PUBLIC_ marks values safe for the client and inlined at build time. I gitignore .env.local and never put tokens in public vars.”

Further reading

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Related guides