How to configure Next.js environmental variables

In this post, you’ll learn how to manage environment variables in Next.js using .env files. We’ll cover public vs. private variables, environmental variables file hierarchy, runtime limitations, and best practices for secure configuration in development and production.

What are environmental variables in Next.js?

Environment variables in Next.js are runtime configuration values defined outside the source code and injected into the application during build or runtime. They are loaded from .env files or the system environment and accessed using process.env.

Next.js supports multiple environment files: .env, .env.local, .env.development, .env.production, and .env.test. These files are evaluated based on the current environment mode (NODE_ENV), and Next.js prioritizes .env.local for local overrides.

Next.js restricts which environment variables are exposed to the browser. Only variables prefixed with NEXT_PUBLIC_ are embedded in the client-side bundle. Variables without this prefix remain server-only, accessible exclusively on the Node.js backend. This division allows sensitive data like database credentials to stay on the server, while public-facing configuration like feature flags or API base URLs can be exposed to the frontend safely.

Environment variables are available in both server-side code (API routes, getServerSideProps, getStaticProps) and client-side code (via NEXT_PUBLIC_*). However, any variable used in client-side code must be prefixed appropriately, or it won’t be included in the compiled JavaScript sent to the browser.

---

Editor’s note: This post was updated by Muhammed Ali in April 2025 to account for Next.js 15+ updates, explain the importance of environmental variables, and provide best practices for managing environmental variables.

---

Why are environmental variables important?

Environment variables allow separation between code and configuration. This ensures that the same codebase can run in multiple environments (development, staging, production) without changes to source files. Instead of hardcoding base URLs, API keys, feature toggles, or analytics tokens, they are abstracted through environment variables that are injected at build time or runtime, depending on the deployment setup.

This separation becomes important in CI/CD pipelines. During the build process, the .env.production file or runtime variables set in the cloud platform define values such as the backend service URL, feature flags, and third-party service credentials. Modifying these values doesn’t require rebuilding the code unless the variable is needed at build time (like those used during static generation).

For variables only used at runtime, the application can remain unchanged and adapt based on the deployed environment, especially with dynamic routes using getServerSideProps.

Getting started with environmental variables

Environment variables consist of name-value pairs, like in the example below:

API_KEY=1234
DB_CONN_STRING="http://localhost:3000"

An application can have different requirements when running in development, testing, and production environments. Instead of having different codebases for the same application, where each codebase is tailored towards a specific environment, an application can have a single codebase whose behavior in the different environments is determined using the environment variable settings.

The application can read the environment variable settings and modify its behavior to meet the requirements of that specific environment. This keeps the codebase short, clean, and organized:

process.env.API_KEY;
process.env.DB_CONN_STRING;

In a development environment, tools for code formatting, linting, and testing are essential.

However, these tools are not necessary in the production stage. When working with tools such as npm, setting the value of the built-in NODE_ENV environment variable to production will install dependencies that the application needs in production, excluding those needed in the development stage. This behavior is configurable if necessary.

Similarly, during development, you may need to set up a local instance of your database server separate from the production server. You will have to use environment variables to pick the correct database connection string.

Usually, modifying an environment variable modifies the behavior of an application without requiring you to rebuild or redeploy the application. But in frameworks like Next.js, some environment variables are hardcoded in the codebase at build time. You may need to build and redeploy after modifying an environment variable.

Built-in support for environment variables in Next.js

As mentioned earlier, Next.js has built-in support for environment variables. To start using them, you can declare .env.local at the root of your project directory:

API_KEY=123456789
USERNAME=username
PASSWORD=password

Next.js will load the above environment variables into the process.env object out of the box so that you can access them in the Node.js environment:

export async function getStaticProps() {
  console.log(process.env.API_KEY); 
  console.log(process.env.USERNAME);
  console.log(process.env.PASSWORD);
}

The above environment variables are only available in the Node.js environment and are referred to as private environment variables. Prefixing the variable name with NEXT_PUBLIC_ turns them into public environment variables:

NEXT_PUBLIC_API_KEY=123456789
NEXT_PUBLIC_USERNAME=username
NEXT_PUBLIC_PASSWORD=password

Public environment variables are available both in the browser and Node.js environments. We will explore public and private environment variables later in this article.

In addition to the .env.local file, Next.js also gives you the flexibility to store constants and default values in .env, env.development, and env.production environment files. These files are not meant for storing secrets, but rather for environment-specific configurations and settings.

As its name suggests, the env.development file is for environment variables you want to use only in development. In Next.js, you can launch the development server using the next dev command.

The variables you declare in the env.development file won’t be available in production.
The env.production file, on the other hand, is for variables that you want to use only in production. The next start command builds the project and launches the production environment. The variables you declare in the env.production file won’t be available in the development environment.

The variables you declare in the .env file will, however, be available in both development and production environments. Be aware that an environment variable that you look up dynamically, such as in the example below, will not be hardcoded into your production build as we just described:

const variableName = 'BASE_URL';
console.log(process.env[variableName]);

const envir = process.env;
console.log(envir.BASE_URL);

Building a sample application

You can use this sample application to try out the examples in this article. Follow the steps below to clone the repository to your machine and experiment with the environment variables in this article.

First, clone a sample application. Use git clone to clone the sample application to your machine. Then, install dependencies by running the npm install command.

There are several environment variable files at the root of your project directory. In Next.js, you only store secrets in the env.local file. Because environment variables holding secrets should not be shared, there is a env.local.template file you can use to create your env.local file.

To add secrets, create a env.local file at the root of your project repository and copy the contents of env.local.template into it. You can add any secrets you don’t want to expose in a version control system in the env.local file.

Next, you can launch the development server using the npm run dev command. The environment variables in the .env.development file are available only in the development environment. On the other hand, you can build the project and launch the production server using the npm run build and npm run start commands. The environment variables in the .env.production file are available only in the production environment.

Now, the environment variables in the .env file are available in both the development and production environments.

Public and private environment variables in Next.js

As we introduced earlier, Next.js environment variables can be categorized into public and private environment variables, but they are private by default.

Private environment variables are only accessible from the Node.js environment. You can declare private environment variables in any of your .env* files like so:

ENV_VARIABLE=env_variable

To make an environment variable public, prefix its name with NEXT_PUBLIC_ as in the example below:

NEXT_PUBLIC_ENV_VARIABLE=nex_public_env_variable

At build time, Next.js will access and replace references to the public environment variables with their actual values in the codebase bundled for the browser environment.

Therefore, in the example below, process.env.NEXT_PUBLIC_ENV_VARIABLE will be replaced in line with the actual value of the environment variable at build time:

<p>{process.env.NEXT_PUBLIC_ENV_VARIABLE}</p>

Public environment variables are mostly used for storing constants or default values that you don’t want to import or declare in multiple files. You can declare such variables once in a .env* file, as in the example above, and access them from anywhere in your codebase. They are available both in the browser and in Node.js.

Using environment variables in local development vs. production

The requirements of an application while in development may not be the same as those in production. Therefore, some environment variables may only be required in development, others in production, and some in both environments.

For example, if you declare the environment variables below in the .env.production file, they will be available only in the production environment:

BASE_URL='http://localhost:3000'
NEXT_PUBLIC_BASE_URL='http://localhost:3000'

Regardless of the file in which you declare the above environment variables, the BASE_URL environment variable will be available in the Node.js environment because it is a private variable. And NEXT_PUBLIC_BASE_URL will be available in both the browser and Node.js environments because it is a public environment variable.

Manipulating environment variables with next.config.js

Next.js offers flexible ways of working with environment variables. You can use the legacy env property of the next.config.js file to configure environment variables, or the newer, more intuitive, and ergonomic .env* files described above.

You can declare the environment variable as a property of the env object in the next.config.js file and access it in your codebase as a property of the process.env object:

module.exports = {
  env: {
    BASE_URL: "http://localhost:3000",
  },
};

Be aware that using the next.config.js file for your environment variables will inline the values of the variables at build time and bundle them in your frontend code, irrespective of whether you prefix the variable name with NEXT_PUBLIC_ or not:

export const App = () => {
  return <p>{process.env.BASE_URL}</p>
}

Dynamic environment variables in Next.js

Next.js will evaluate all references to environment variables and hardcode them in your client code at build time. After that, all the evaluated values won’t respond to changes in the environment variable.

If your frontend application needs access to dynamic environment variables at runtime, you should set up your own API and provide the variables to your client code.

Similarly, dynamically looking up or destructuring environment variables in your frontend code, as in the example below, won’t work. The value of the environment value will be undefined. Always access your environment variables using process.env.ENV_VARIABLE_NAME on the client side:

const varName = "BASE_URL";
console.log(`${varName} = ${process.env[varName]}`);

const { BASE_URL } = process.env;
console.log(`${varName} = ${BASE_URL}`);

Order of environment variable lookup in Next.js

As explained above, you can declare environment variables in different files. These files are for environment variables that are usually made available in specific environments.

Next.js follows the order below when looking for an environment variable and stops after finding the variable it needs. The value of NODE_ENV is set to development in a development environment, production in a production environment, and test in a test environment:

process.env
env.${NODE_ENV}.local
env.local (env.local is not checked when NODE_ENV is test)
env.${NODE_ENV}
.env

If you declare the same environment variable in multiple files, the environment variable declared in the lowest file in the above list wins.

Interpolating environment variables in Next.js

In Next.js, you can create an environment variable by referencing or composing other environment variables using the ${VARIABLE_NAME} syntax. Next.js will expand and replace any referenced variable with its actual value.

The example below uses the BASE_URL and API_KEY environment variables to create API_URL. The value of the API_URL variable will evaluate to https://www.logrocket.com/api/v1?apiKey=12345:

BASE_URL="https://www.logrocket.com"
API_KEY=12345
API_URL="${BASE_URL}/api/v1?apiKey=${API_KEY}"

Such a composition avoids repetition and keeps your environment variable files organized. You can now reference each environment variable independently from your codebase:

console.log(process.env.BASE_URL);
console.log(process.env.API_KEY);
console.log(process.env.API_URL);

Cross-file environment variable referencing is also possible in Next.js. You can reference an environment variable declared in the env.local file from the .env file. However, you should pay attention to the order of the environment variable lookup as highlighted above if you have variables with similar names in different files.

Referencing a variable declared in .env.development from .env.production and vice versa won’t work because those environment variables will only be available in their respective environments.

Best practices for managing environmental variables

Managing environment variables poorly can lead to misconfigurations, security leaks, or inconsistent behavior across environments. Next.js supports multiple .env files and variable scoping rules, but it’s up to the developer to enforce structure and safety. The following practices help maintain clarity, prevent accidental exposure, and ensure reliable application behavior in every environment.

Use .env.local for local-only secrets, and never commit it to version control

.env.local is intended for environment-specific overrides that should not be shared, such as local database credentials, test API tokens, or private keys. This file is ignored by default in .gitignore. Keeping sensitive data in .env.local ensures each developer can configure their environment without risking exposure in commits or pull requests.

Prefix only the necessary variables with NEXT_PUBLIC_

Variables prefixed with NEXT_PUBLIC_ are embedded into the client-side bundle. Only expose values that are explicitly safe for the browser. Avoid overusing this prefix; leaking internal service URLs, tokens, or feature gates into the client increases the attack surface and creates coupling between server and client logic.

Validate environment variables at startup using a schema

Relying on the implicit presence of environment variables increases the chance of silent failures. Instead, define a schema using libraries like zod, joi, or env-var, and validate all required variables at application boot. This helps catch configuration errors early during deployment or local development.

Avoid hardcoding environment-specific logic in the codebase

Do not use if (process.env.NODE_ENV === 'production') as the primary switch for behavior. Instead, use explicit environment variables that define the behavior, such as FEATURE_X_ENABLED=true or USE_CACHE_LAYER=false. This makes the codebase more readable and decouples environment control from build stages.

Conclusion

Environment variables influence how an application runs or behaves in different contexts and environments. Next.js, like most web frameworks, has the necessary setup for flexibly configuring and using environment variables in your application.

In this article, we explored the differences between private and public environment variables in Next.js. We also learned about functionalities that allow you to declare development-only and production-only environment variables, such as the .env.development and env.production files.

Finally, we learned that in a typical Next.js project, you only need the .env.local file to store credentials that you want to keep secret. Always add the .env.local file to your .gitignore file to avoid exposing your secrets in a version control system like Git.

Happy coding!