Environment variables in production in NextJS - Deep Dive

Overview - Environment variables in production

What is it?

Environment variables are special settings stored outside your code that tell your Next.js app important information, like secret keys or URLs. In production, these variables help your app behave correctly and securely without exposing sensitive data. They are set on the server or hosting platform and accessed by your app when it runs. This keeps secrets safe and makes your app flexible for different environments.

Why it matters

Without environment variables, you would have to hardcode secrets and settings directly in your code, risking leaks and making updates difficult. This could expose passwords or API keys to anyone who sees your code. Environment variables let you keep secrets safe and change settings without touching your code, which is crucial for security and smooth updates in real-world apps.

Where it fits

Before learning environment variables, you should understand basic Next.js app structure and how to run apps locally. After this, you can learn about deployment platforms like Vercel or AWS and how they manage environment variables. Later, you can explore advanced security practices and secrets management tools.

Mental Model

Core Idea

Environment variables are secret notes your app reads at runtime to know how to behave without putting secrets in the code.

Think of it like...

It's like a chef who keeps secret recipes in a locked box in the kitchen instead of writing them on the menu. The chef reads the recipe only when cooking, keeping secrets safe from customers.

┌─────────────────────────────┐
│  Production Server / Host   │
│ ┌─────────────────────────┐ │
│ │ Environment Variables   │ │
│ │ (Secrets & Settings)    │ │
│ └────────────┬────────────┘ │
│              │              │
│      ┌───────▼────────┐     │
│      │ Next.js App    │     │
│      │ Reads variables│     │
│      └────────────────┘     │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What are environment variables

Concept: Introduce environment variables as external settings for apps.

Environment variables are values stored outside your app's code. They can hold things like API keys, database URLs, or feature flags. Your app reads these values when it runs, so you don't have to write secrets directly in your code files.

Result

You understand that environment variables keep secrets and settings separate from code.

Understanding that environment variables separate secrets from code is the first step to building secure and flexible apps.

2

Foundation

How Next.js accesses environment variables

Concept: Explain how Next.js reads environment variables during build and runtime.

Next.js reads environment variables from the system or hosting platform. Variables starting with NEXT_PUBLIC_ are exposed to the browser, while others stay server-only. You can access them in your code using process.env.VARIABLE_NAME.

Result

You can use environment variables in Next.js code safely, knowing which are public or private.

Knowing the difference between public and private variables prevents accidental leaks of secrets to users.

3

Intermediate

Setting environment variables in production

🤔Before reading on: do you think environment variables are set inside your code or on the hosting platform? Commit to your answer.

Concept: Show how to set environment variables on production hosts like Vercel or custom servers.

In production, you do NOT put environment variables in your code. Instead, you set them on your hosting platform's dashboard or server environment. For example, on Vercel, you add variables in the project settings. Your app reads these when it starts.

Result

Your app uses the correct secrets and settings in production without exposing them in code.

Understanding that environment variables live outside code in production is key to secure deployments.

4

Intermediate

Using .env files locally and in production

🤔Before reading on: do you think .env files should be uploaded to production servers? Commit to your answer.

Concept: Explain the role of .env files for local development and why they differ from production variables.

You use .env files locally to store environment variables for development. These files should NOT be uploaded to production or version control. In production, environment variables are set directly on the server or platform, not from .env files.

Result

You keep local secrets separate and avoid leaking them to production or public repos.

Knowing the difference between local .env files and production variables prevents accidental secret leaks.

5

Advanced

Handling environment variables during Next.js build

🤔Before reading on: do you think changing environment variables after build affects the running Next.js app? Commit to your answer.

Concept: Explain that Next.js reads environment variables at build time and how this affects updates.

Next.js reads environment variables when building the app. If you change variables after build, the app won't see those changes until rebuilt and redeployed. This means secrets or URLs must be set correctly before building.

Result

You understand why redeploying is needed after changing environment variables.

Knowing build-time reading of variables helps avoid confusing bugs where changes seem ignored.

6

Expert

Security risks and best practices for production variables

🤔Before reading on: do you think all environment variables are equally safe to expose to the browser? Commit to your answer.

Concept: Discuss risks of exposing secrets and how to protect them in Next.js production apps.

Never expose secrets by prefixing them with NEXT_PUBLIC_. Only public info should have this prefix. Use server-side code or API routes to keep secrets hidden. Also, restrict access to your hosting platform's environment variable settings to trusted people only.

Result

Your app keeps secrets safe and avoids accidental exposure to users or attackers.

Understanding how to separate public and private variables is critical to preventing security breaches.

Under the Hood

Next.js reads environment variables from the system environment at build time and runtime. Variables prefixed with NEXT_PUBLIC_ are embedded into the client-side JavaScript bundle, making them accessible in the browser. Other variables remain only on the server side. During build, Next.js replaces process.env.VARIABLE_NAME with the actual value, so the app code contains the values directly after build.

Why designed this way?

This design balances security and convenience. By embedding public variables in the client bundle, Next.js allows safe sharing of non-sensitive data. Keeping other variables server-only protects secrets. Reading variables at build time enables static optimization and faster apps. Alternatives like runtime environment injection would complicate static builds and caching.

┌───────────────┐       ┌─────────────────────┐
│ System Env    │──────▶│ Next.js Build Process│
│ (Variables)   │       │ - Reads variables    │
└───────────────┘       │ - Embeds NEXT_PUBLIC_│
                        │   in client bundle   │
                        │ - Keeps others server│
                        └─────────┬───────────┘
                                  │
                      ┌───────────▼───────────┐
                      │ Next.js App Running    │
                      │ - Client sees public   │
                      │   variables            │
                      │ - Server sees all vars  │
                      └────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think environment variables prefixed with NEXT_PUBLIC_ are private? Commit yes or no.

Common Belief: All environment variables are private and safe from users.

Reality: Variables starting with NEXT_PUBLIC_ are included in the client-side code and visible to anyone using the app.

Why it matters: Mistakenly putting secrets in NEXT_PUBLIC_ variables exposes them to attackers and users, risking security breaches.

Quick: Do you think changing environment variables on the server immediately updates the running Next.js app? Commit yes or no.

Common Belief: Changing environment variables on the server instantly changes app behavior without redeploying.

Reality: Next.js reads environment variables at build time, so changes require rebuilding and redeploying to take effect.

Why it matters: Expecting instant updates leads to confusion and bugs when changes seem ignored.

Quick: Do you think .env files should be committed to public repositories? Commit yes or no.

Common Belief: It's safe to commit .env files with secrets to public code repositories for convenience.

Reality: .env files often contain secrets and should never be committed to public repos to avoid leaks.

Why it matters: Leaking secrets publicly can lead to unauthorized access and data breaches.

Quick: Do you think environment variables can be used to configure client-side behavior securely? Commit yes or no.

Common Belief: All environment variables can be used safely on the client side to configure app behavior.

Reality: Only variables prefixed with NEXT_PUBLIC_ should be used on the client; others must stay server-side to protect secrets.

Why it matters: Misusing variables can expose sensitive data or cause app errors.

Expert Zone

1

Next.js replaces process.env.VARIABLE_NAME with the actual value at build time, so dynamic runtime changes require special handling like API routes.

2

Using NEXT_PUBLIC_ prefix is a deliberate design choice to clearly separate public from private variables, reducing accidental leaks.

3

Some hosting platforms inject environment variables differently, so understanding platform-specific behavior is crucial for consistent deployments.

When NOT to use

Environment variables are not suitable for storing large data or secrets that require rotation without redeployment. In such cases, use dedicated secrets management services like HashiCorp Vault or AWS Secrets Manager. Also, avoid using environment variables for client-only configuration that changes frequently; use API calls or feature flags instead.

Production Patterns

In production, teams store secrets in platform dashboards (e.g., Vercel, Netlify) and restrict access. They use .env.local files only for development. CI/CD pipelines inject environment variables securely during build. Secrets are accessed only in server-side code or API routes, never exposed directly to the client. Variables are versioned and rotated regularly for security.

Connections

Secrets Management

Builds-on

Understanding environment variables helps grasp how secrets management tools securely provide secrets to apps without hardcoding.

Continuous Integration/Continuous Deployment (CI/CD)

Builds-on

CI/CD pipelines often inject environment variables during build and deploy steps, linking environment variables to automated workflows.

Operating System Environment Variables

Same pattern

Environment variables in Next.js follow the same principle as OS environment variables, showing how apps use system-level settings for configuration.

Common Pitfalls

#1 Exposing secrets by prefixing them with NEXT_PUBLIC_

Wrong approach:

NEXT_PUBLIC_API_KEY=supersecretkey

Correct approach:

API_KEY=supersecretkey

Root cause:

Misunderstanding that NEXT_PUBLIC_ variables are visible to the browser, leading to accidental exposure.

#2 Committing .env files with secrets to public repositories

Wrong approach:

git add .env
# pushes secrets to public repo

Correct approach:

Add .env to .gitignore and set variables only on hosting platform

Root cause:

Not knowing that .env files contain sensitive data and should be kept out of version control.

#3 Expecting environment variable changes to apply without rebuilding

Wrong approach:

Change variable on server and expect app to use new value immediately

Correct approach:

Change variable, then rebuild and redeploy Next.js app

Root cause:

Not realizing Next.js reads variables at build time, not runtime.

Key Takeaways

Environment variables keep secrets and settings outside your code, making apps safer and more flexible.

Next.js reads environment variables at build time; changes require rebuilding and redeploying to take effect.

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser and should never contain secrets.

Use .env files only for local development and never commit them to public repositories.

In production, set environment variables securely on your hosting platform or server, and restrict access carefully.