How to Configure Environment Variables in Next.js

Managing environment variables is essential for any Next.js app to handle sensitive data and configuration settings securely. Without proper configuration, you risk exposing secrets or facing deployment issues. This guide explains how to set up environment variables in Next.js effectively.

You'll learn the exact steps to configure environment variables, common pitfalls to avoid, and best practices to keep your app secure and maintainable across development, staging, and production environments.

What do you need before configuring environment variables in a Next.js app?

• Next.js version 10 or above: Ensure your Next.js version supports built-in environment variable loading by running npm list next.
• .env file support: Your project root must contain .env files for different environments; missing these files means variables won't load during build or runtime.
• Node.js 12 or newer: Next.js requires Node.js 12+; older versions may cause unexpected behavior when reading environment variables.
• Proper variable naming conventions: Variables exposed to the browser must start with NEXT_PUBLIC_; missing this prefix will prevent client-side access and cause undefined errors.

How do you configure environment variables in a Next.js app step by step?

Step 1: Create environment variable files

touch .env.local .env.production .env.development

Next.js automatically loads these files based on the environment, so organizing variables here is crucial for environment-specific behavior.

Step 2: Define variables with correct prefixes

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_PASSWORD=supersecret

Variables without the prefix remain server-only, protecting sensitive data like database passwords.

Step 3: Access variables in your Next.js code

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Remember, only variables prefixed with NEXT_PUBLIC_ are available on the client side.

Step 4: Restart the development server

npm run dev

After adding or changing environment variables, restart your Next.js development server to load the new values.

Step 5: Secure environment variables in production

vercel env add NEXT_PUBLIC_API_URL production

For production, set environment variables on your hosting platform instead of committing .env.production to version control.

Step 6: Use environment variables in API routes or server code

export default function handler(req, res) {
  const dbPassword = process.env.DATABASE_PASSWORD;
  // Use dbPassword securely here
}

What are common environment variable errors in Next.js and how do you fix them?

Error 1: Environment variable is undefined on the client side

• Symptom: Accessing process.env.MY_VAR in the browser returns undefined.
• Cause: Variable lacks the NEXT_PUBLIC_ prefix, so Next.js excludes it from client bundles.
• Fix: Rename the variable to start with NEXT_PUBLIC_ in both .env and code.

Error 2: Changes to .env files not reflected after restart

• Cause: Next.js caches environment variables during build; changes require a full rebuild.
• Fix: Stop the server completely and run npm run dev or rebuild for production.

Error 3: Sensitive variables exposed in client bundles

• Cause: Variables without NEXT_PUBLIC_ prefix are imported in client-side code.
• Fix: Move sensitive logic to API routes or server-side functions and avoid referencing secrets in client code.

Error 4: Missing .env files in production causing build failures

• Cause: .env.production file not present or variables not set in hosting environment.
• Fix: Set required variables in hosting platform dashboard or add .env.production securely.

What are best practices for configuring environment variables in Next.js?

• Use .env files for local development only: Keep .env.local uncommitted to avoid leaking secrets.
• Prefix client variables with NEXT_PUBLIC_: This clearly separates public from private variables, preventing accidental exposure of secrets.
• Validate required variables at build time: Use scripts or libraries to check that all necessary variables are set.
• Do not hardcode secrets in code: Always read sensitive data from environment variables to allow easy rotation.

Common questions on configuring environment variables in Next.js

Why do some environment variables not appear in the browser in Next.js?

Only variables prefixed with NEXT_PUBLIC_ are exposed to client-side code. Variables without this prefix remain server-only to protect sensitive data.

Can I use environment variables in Next.js API routes?

Yes, API routes run on the server and can access all environment variables, including those without the NEXT_PUBLIC_ prefix, allowing secure use of secrets.

How do I keep environment variables secure in production Next.js apps?

Set environment variables through your hosting platform's dashboard or CLI instead of committing .env files. This prevents secrets from being exposed in version control.

What happens if I forget to restart the Next.js server after changing .env files?

The app will continue using old environment variable values until you restart the server or rebuild. This can cause confusion and outdated behavior during development.

Is it possible to have different environment variables for development and production in Next.js?

Yes, Next.js supports multiple .env files like .env.development and .env.production to define environment-specific variables that load automatically based on the environment.