How to Properly Set Up Environment Variables undefined in Next.js

Next.js, Environment Variables,

Sumeet Shroff
By Sumeet Shroff
April 18, 2024
How to Properly Set Up Environment Variables undefined in Next.js

Understanding Environment Variables in Next.js

Environment variables in Next.js are crucial for managing configuration and keeping sensitive data, like API keys and database passwords, secure and out of your codebase. In Next.js, environment variables are typically defined in a .env file, which is placed at the root of the project. These variables can then be accessed in your application using process .env.YOUR_VARIABLE_NAME. Next.js also supports different sets of environment variables for development and production environments, enabling you to manage your application's configuration seamlessly across multiple stages.

To ensure these variables are only exposed where necessary, Next.js differentiates between server-side and client-side variables, with the latter requiring a specific prefix (NEXTPUBLIC) to make them accessible in the browser. This system not only enhances security but also aids in the maintainable and scalable configuration of Next.js applications.

Common Reasons Why Environment Variables Are Undefined in Next.js

Incorrect .env File Placement: Next.js expects environment variable files to be located at the root of your project. If the .env file is placed in a subdirectory or incorrectly named, the variables won’t be loaded.

Naming Mistakes:

Environment variables must be named correctly in your .env files. Simple typos or using reserved JavaScript keywords as names can lead to variables that are either undefined or not behaving as expected.

Improper Access in Code:

Next.js requires that environment variables to be used in the browser have names prefixed with NEXTPUBLIC. Without this prefix, variables are only available on the server-side, leading to them being undefined in the client-side code.

Not Restarting the Server:

After adding new variables to your .env files, you need to restart your Next.js server. The environment variables are loaded when the server starts, so changes made while the server is running won't be recognized until a restart.

Variable Overwrites:

If environment variables are set both in .env files and externally (like in a CI/CD pipeline), there might be conflicts or overwrites that cause some variables to be undefined due to unexpected values or overwrites.

Scope of Environment Variables:

Developers sometimes forget that environment variables are not reactive and won't update within a running session if their values change externally. They need to be reloaded by restarting the server or application.

Build-Time vs. Runtime Variables:

Next.js statically optimizes pages at build time. If environment variables are expected to be available at runtime, but are only included at build time, they will not appear as expected when the application is running.

Step-by-Step Guide to Configuring Environment Variables in Next.js

Configuring environment variables in Next.js is a straightforward process that can significantly enhance the security and flexibility of your application.

Create Environment Variable Files:

  • At the root of your Next.js project, create .env.local for local development settings. This file should not be committed to your source control.

  • You can also create other environment-specific files like .env.development, .env.production, and .env.test depending on your deployment stages.

Define Your Variables:

Open your .env file and define your variables in the format KEY=VALUE. For example:



Remember, only variables prefixed with NEXTPUBLIC will be accessible from the client-side JavaScript.

Access Environment Variables in Your Code:

Use process.env.YOUR_VARIABLE_NAME to access your variables within your Next.js application. For example:

const apiKey = process.env.API_KEY;

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Use Variables in next.config.js:

If you need to use environment variables in your next.config.js, you can load them using the dotenv package or manually:

require('dotenv').config(); module.exports = { env: { customKey: process.env.CUSTOM_KEY, }, };

Restart Your Development Server:

After setting up or updating your environment variables, restart your Next.js development server to ensure the new settings are loaded.

Secure Your Variables:

Make sure that any sensitive information like API keys are not exposed to the client-side unless absolutely necessary. Use server-side fetching or API routes in Next.js to keep this information secure.

Test Your Configuration:

Before deploying your application, locally test to ensure all variables are loaded correctly and function as expected across different parts of your application.

Deploy Your Application:

When deploying your application, ensure that all necessary environment variables are set in your deployment environment. Platforms like Vercel and Netlify provide easy interfaces to set environment variables.

Troubleshooting Undefined Environment Variables in Next.js

When environment variables appear as undefined in a Next.js application, it can be frustrating.

Check .env File Location and Naming:

Ensure your .env files are placed at the root of your project directory. Verify the names of the files (like .env.local, .env.production) are correct according to the environment.

Verify Variable Naming and Prefixes:

Double-check the spelling of your environment variable names. Remember, variables that need to be accessed on the client-side must start with NEXTPUBLIC.

Restart the Server:

Changes to .env files are not hot reloaded. Restart your development server to ensure all environment variables are loaded.

Inspect Build and Start Logs:

Look at the logs during the build and start phases. Sometimes, errors related to environment variables are logged here, especially during production builds.

Check for Overwrites:

Ensure that environment variables are not being overwritten by other configurations or during the deployment process. Check if your deployment service or CI/CD pipeline might be setting environment variables that override your .env values.

Use Default Values:

Temporarily assign default values in your code to test if the issue is from misconfiguration or access:

const apiKey = process.env.API_KEY || 'default_value';

Environment Specific Files:

Ensure you are not defining environment variables in the wrong .env file for your current environment (development vs production).

Logging and Debugging:

Add console logs to check the values of environment variables at runtime. This can help identify where the breakdown occurs.

Using Next.js Environment Variables with Third-Party Services

Integrating third-party services with Next.js using environment variables can streamline configuration and enhance security.

Store API Keys Securely:

Use .env files to store API keys and sensitive information. Ensure these keys are only available to server-side processes if they are sensitive.

Access Variables in API Routes:

Utilize Next.js API routes to interface with third-party services. Use environment variables within these routes to keep sensitive data out of the client-side code:

// pages/api/data.js export default function handler(req, res) { const apiKey = process.env.API_KEY; // Use apiKey with third-party service }

Client-Side Access:

If you need to use environment variables directly in the client-side code (for example, public API URLs), ensure they are prefixed with NEXTPUBLIC.

Dynamic Import of Configuration:

For more complex integrations, consider dynamically importing configuration settings based on the environment, which can leverage different sets of environment variables.

Secure Transmission:

Always use HTTPS to communicate with third-party APIs to prevent the interception of sensitive data.

Environment Variable Management in Deployment:

Configure environment variables in your production environment or on platforms like Vercel or Netlify, ensuring that all necessary variables are set for your application to function correctly.

Advanced Techniques for Dynamic Environment Variables in Next.js

Handling environment variables dynamically in Next.js can add flexibility and scalability to your application.

Environment-Specific Logic:

Implement custom logic in your next.config.js to dynamically set environment variables based on additional contexts such as branch names, deployment stages, or custom environment flags.

Server-Side Configurations:

Use server-side code to determine environment variables at runtime. This can be particularly useful for multi-tenant applications where configuration might change based on the incoming request or user:

// pages/api/config.js export default function handler(req, res) { const host =; const apiKey = host === '' ? process.env.EXAMPLE_API_KEY : process.env.DEFAULT_API_KEY; res.status(200).json({ apiKey }); }

Integrating with Configuration Services:

Use services like AWS Parameter Store, Google Cloud Secret Manager, or HashiCorp Vault to manage environment variables dynamically. Retrieve these configurations at runtime or during the build process.

Dynamic Imports for Configurations:

Use dynamic imports to load configuration files based on the environment, allowing for more granular control over which settings are loaded in different scenarios.

Environment Variables in Static Generation:

Use getStaticProps or getServerSideProps to pass environment variables to your pages at build time or request time, allowing for content customization based on the environment:

export async function getStaticProps(context) { return { props: { apiEndpoint: process.env.NEXT_PUBLIC_API_ENDPOINT, }, }; }

Testing Strategies for Next.js Apps with Environment Variables

Testing Next.js applications that use environment variables requires careful setup to ensure consistency and reliability.

Mocking Environment Variables:

Use libraries such as jest to mock environment variables during testing. This allows you to simulate different environments and test how your application behaves with various configurations:

  • beforeEach(() => { process.env.TEST_VAR = 'test'; });

  • afterEach(() => { delete process.env.TEST_VAR; });

Environment-Specific Test Configurations:

Create test-specific environment files, like .env.test, and load these configurations during your testing setup to ensure that tests are not dependent on your local or production environment settings.

Integration Testing:

Perform integration tests that involve environment variables to ensure that components interact correctly with the configured services. For example, testing API routes within Next.js that rely on environment variables to function.

End-to-End Testing with Environment Variables:

Use tools like Cypress or Puppeteer to run end-to-end tests, setting environment variables in these tools to mimic production settings, verifying the complete flow of the application.

Continuous Integration (CI) Environments:

Ensure that your CI pipeline is correctly set up to inject the necessary environment variables during the test phase. This helps catch issues before deployment.

Security and Leakage Tests:

Regularly check for unintended exposure of sensitive environment variables, especially in client-side code, as part of your security testing practices.

How do I access environment variables in Next.js?

In Next.js, environment variables can be accessed using the process.env object. To make an environment variable available to the browser, it must be prefixed with NEXTPUBLIC. Here's a quick example:

Defining Environment Variables:

In your project's root, create a file named .env.local and add your variables:



Accessing Environment Variables:

// Accessible only on the server-side

const serverKey = process.env.SECRET_API_KEY;

// Accessible on both server and client-side

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Why is my env variable not being set?

There are several common reasons why an environment variable might not be set in your Next.js application:

1. Incorrect .env File Placement: Make sure your .env file is located at the root of your project.

2. Server Not Restarted: Next.js requires a server restart to pick up changes in .env files.

3. Naming Issues: Ensure there are no typos in your variable names and that client-accessible variables are prefixed with NEXTPUBLIC.

4. File Naming: Check that the environment file name matches your environment (.env.local, .env.production, etc.).

5. Overwrites: Other configurations or system environment settings might be overriding your variables.

How to set environment variables in JavaScript?

In a JavaScript project, you typically set environment variables in your node environment or use a package like dotenv to load variables from a .env file. Here’s how you can set it up using dotenv:

Install dotenv:

npm install dotenv

Create a .env file at the root of your project:


Load and use the environment variables in your JavaScript code:


const apiKey = process.env.API_KEY; console.log(apiKey); // Outputs: 12345

How do you set environment variables in Linux?

Setting environment variables in Linux can be done temporarily in the terminal or permanently by editing profile files. Here’s how to do both:

Temporarily Setting Environment Variables:

export VARIABLE_NAME=value

Permanently Setting Environment Variables:

Open your user’s profile script in a text editor. For most distributions, this will be ~/.bashrc or ~/.profile.

Add the export statement to the end of the file:

export VARIABLE_NAME=value

Save the file and reload it:

source ~/.bashrc

These instructions should help you effectively manage and troubleshoot environment variables across different scenarios and platforms.

Frequently Asked Questions

  1. Why are my environment variables undefined in my Next.js application?

Answer: There are several common reasons why environment variables might appear as undefined:

Incorrect File Placement: Ensure your .env files are at the root of your project directory.

Wrong Naming Convention: Variables intended for client-side must be prefixed with NEXTPUBLIC.

Server Not Restarted: Environment variables are loaded at server startup, so any changes require a server restart.

File Naming: Make sure your environment file name is appropriate for the environment (e.g., .env.local for local development).

  1. How do I access environment variables in both the server and client-side in Next.js?

Answer: To access environment variables on the server-side, use process.env.VARNAME. For client-side access, you must prefix your environment variables with NEXT_PUBLIC, making them process.env.NEXT_PUBLIC_VAR_NAME.

  1. How can I ensure my environment variables are secure in Next.js?

Answer: Keep sensitive information secure by only using sensitive variables on the server-side or in API routes. Never prefix sensitive variables with NEXTPUBLIC, as this makes them accessible on the client-side. Consider using secrets management tools or services for handling production secrets.

  1. What is the best way to manage environment variables for different deployment environments in Next.js?

Answer: Use specific .env files for different environments like .env.development, .env.production, and .env.test. This allows you to control environment-specific variables and ensures that only the relevant configuration is loaded based on the NODE_ENV setting.

  1. How can I troubleshoot an environment variable that works locally but not in production?


Check Deployment Configuration: Ensure that your deployment service (e.g., Vercel, Netlify) has the correct environment variables set in its configuration settings.

Review Build Logs: Sometimes, environment variables are not included or misconfigured during the build process. Reviewing build logs can provide insights into what went wrong.

Runtime vs. Build-time: Remember that variables in Next.js can be set at build-time and might not be dynamic in production if set incorrectly. Ensure that runtime-required variables are not mistakenly assumed to be available as build-time variables.

Sumeet Shroff

Sumeet Shroff

Sumeet Shroff is a respected web developer and tech thought leader in Next.js. Build scalable, secure online apps that use environmental configurations is his speciality.

Get Special Offers and Get Latest Updates from our blogs!

Subscribe to our newsletter for exclusive offers and discounts on our packages. Receive bi-weekly updates from our blog for the latest news and insights.