How to Use Environment Variables in Next.js (Without Leaking Them to the Browser)

Environment variables are key-value pairs your app reads at runtime. They are essential for three reasons:

• Store secrets (API keys, database URLs) outside your source code and away from Git history
• Run the same codebase differently in development, staging, and production without code changes
• Prevent credentials from being hardcoded into files that get committed and shared

Next.js reads .env files in a specific order. When the same variable exists in multiple files, .env.local always wins.

.env               # loaded in all environments
.env.local         # loaded in all environments, git-ignored (secrets live here)
.env.development   # loaded only during next dev
.env.production    # loaded only during next build and next start

Next.js runs in two contexts, and environment variables behave differently in each:

• The server (Node.js, API routes, Server Components). Variables are available here by default and never exposed to users.
• The client (the browser). Variables are stripped from the bundle at build time unless you explicitly opt in with the NEXT_PUBLIC_ prefix.

# Safe to expose — use NEXT_PUBLIC_
NEXT_PUBLIC_POSTHOG_KEY=phc_xxx
NEXT_PUBLIC_API_URL=https://api.example.com

# Must stay server-only — no NEXT_PUBLIC_ prefix
DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET_KEY=your-secret-here

Create a .env.local file at the root of your project, at the same level as package.json. How you access a variable depends on the prefix:

• No prefix: server only. Works in Server Components, API routes, and server actions.
• With NEXT_PUBLIC_ prefix: available everywhere, including client components and the browser.

// .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET_KEY=your-secret-here
NEXT_PUBLIC_SITE_URL=http://localhost:3000

// In a Server Component or API route (safe — server only)
const dbUrl = process.env.DATABASE_URL;

// In a Client Component (only works with NEXT_PUBLIC_)
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL;

.env.local is git-ignored, so anyone cloning your repo will not know which variables are required. The .env.example pattern solves this:

• Create a .env.example file and commit it to Git
• List every required variable with blank or placeholder values
• New team members copy it to .env.local and fill in the real values

# .env.example — commit this to Git
DATABASE_URL=
API_SECRET_KEY=
TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_POSTHOG_KEY=

Neither platform reads .env files from your repository. Variables must be added through the dashboard and injected at build time:

• Vercel: open your project > Settings > Environment Variables > add each variable > select environments (Production, Preview, Development) > save > redeploy
• Cloudflare: open your project > Settings > Environment Variables > add variables under Production or Preview > Save and Deploy
• Cloudflare Workers runs at the edge, not in Node.js. Test your variable access after the first deploy.

These four mistakes cause most environment variable issues in Next.js apps:

• Not restarting the dev server. Next.js reads .env.local once at startup. Any new variable requires a full restart.
• Using NEXT_PUBLIC_ on a secret key. If the value is sensitive, it must never have that prefix.
• Hardcoding fallbacks like process.env.MY_KEY || 'default'. This silently hides missing variables in production.
• Not adding variables to CI/CD. GitHub Actions cannot access .env.local. Add all required values to repository secrets instead.

Before shipping, confirm each item:

• .env.local is listed in .gitignore
• No secret keys use the NEXT_PUBLIC_ prefix
• .env.example is committed to Git with blank values
• Production variables are set in the platform dashboard, not committed to any file
• Every API key has the minimum permissions it needs