How to Manage Next.js Environment Variables for Better Security

Next.js has rapidly become the go-to React framework for developers looking to build fast, scalable applications. As a React developer, you might appreciate its built-in support for features like server-side rendering and static site generation. Next.js is versatile enough for everything from small projects to large-scale enterprise applications.

In any development environment, managing environment variables is crucial. They help configure the environment in which your application runs without hard-coding sensitive data like API keys, database passwords, or Google Analytics IDs into your codebase.

Using environment variables, you can safely read sensitive data, ensuring that your app’s runtime environment adjusts to the local development, test environment, and production environment seamlessly.

This blog post aims to enhance your understanding of environment variables in Next.js. You'll learn how to define, manage, and access these variables across multiple environments—from your local file system in development to your production file in deployment.

Understanding Environment Variables

Environment variables are key-value pairs that define various settings or configurations for an application’s operating environment. These variables are crucial because they allow you to manage application settings externally, without hard coding any sensitive or environment-specific data within your application’s source code.

In Next.js, like in many other development environments, environment variables can include database connections, API keys, or even control feature toggles and service endpoints. The primary purpose of environment variables is to enhance the security and flexibility of applications by segregating operational settings from the application code.

This segregation not only protects sensitive information but also facilitates easier transitions between different stages of development—from local development to production environments—without the need for code changes.

1// Example of defining an environment variable in Next.js
2// .env.local file
3DATABASE_USER=janedoe
4DATABASE_PASSWORD=securepassword123

​

Next.js supports the concept of 'default environment variables' which can be specified using .env files for different application environments, such as .env, .env.development, .env.production, and .env.local, with .env.local designed to override the defaults and contain sensitive data, ensuring secure and flexible configuration across various stages of application deployment, including the use of .env.test for the testing environment.

Common Use Cases for Environment Variables in Web Applications

1. Configuring Database Connections: Environment variables enable you to specify different database URLs or credentials for your local development, test environment, and production environments. By using environment variables for these configurations, you ensure that the right database is accessed depending on the runtime environment, which is critical for both functionality and security.

2. API Keys Management: Storing API keys as environment variables keeps them secure and out of your codebase. This practice is particularly important for services like Google Analytics or third-party APIs, where exposing these keys publicly could lead to unauthorized access or misuse. It's essential to safely read environment variables to access API keys and other sensitive information securely across different environments.

3. Feature Flags and Service Endpoints: You can use environment variables to control feature releases or manage service endpoints dynamically. For example, a feature flag can be enabled in a development environment for testing while being disabled in production until it's ready to be launched.

1// Accessing a feature flag from environment variables in Next.js
2if (process.env.FEATURE_NEW_DASHBOARD === 'true') {
3    console.log('New Dashboard feature is enabled.');
4}

​

4. Dynamic Configuration: Adjusting application behavior based on the environment without needing code changes is another powerful use case. This could include turning debugging on or off, modifying log levels, or changing the resource allocation.

How Next.js Handles Environment Variables

Next.js provides a streamlined and robust approach to managing environment variables, designed to facilitate both development and production workflows effectively. Here are some key features:

1. Built-in Load Support for .env Files: Next.js automatically loads environment variables from .env files into process.env. It supports multiple .env files for different environments, such as .env.local, .env.development, and .env.production. This built-in support simplifies the process of managing environment variables across various environments. Utilizing a .env file is crucial for specifying default configurations for application environments, and it's important to add .env and .env.local files to .gitignore to protect sensitive application data.

Next.js determines which environment variable values to use based on their definition order, known as the 'environment variable load order'. This sequence ensures that Next.js stops searching once the variable is found, impacting which value is ultimately used.

2. Public and Private Variables: Next.js distinguishes between public and private environment variables. Variables that should be exposed to the browser, known as 'public environment variables', must be prefixed with NEXT_PUBLIC_, ensuring that only designated variables are accessible on the client side. This naming convention helps prevent accidental exposure of sensitive data and allows these variables to be safely read on the server during dynamic rendering using getServerSideProps or the App Router.

1// Example of using a public environment variable in Next.js
2console.log('Analytics ID:', process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID);

​

3. Environment Variables on Server and Client Side: Next.js allows environment variables to be accessed in both server-side and client-side code. However, for client-side access, variables must be prefixed as public, as mentioned earlier. This dual accessibility is useful for universal rendering.

4. Automatic Inclusion in the Build Time: Next.js includes the environment variables at the build time, meaning that the values are set when you build your application. This is particularly important for production, ensuring that runtime changes to environment variables do not affect the already-built application.

Setting Up Environment Variables in Next.js

Creating .env Files

Next.js supports environment variable management through .env files, allowing you to specify different variables for different environments. This not only simplifies local development but also aids in maintaining consistency across multiple deployment stages. Here's how to set up these files:

1. .env.local: Used for local development settings that should not be shared publicly. This file is loaded for all environments except when running Next.js in production mode.

1DATABASE_PASSWORD=localdevpassword
2NEXT_PUBLIC_API_URL=http://localhost:3000/api

​

2. .env.development: Specifically for development environment settings. It gets loaded when you run next dev.

3. .env.production: Contains variables for the production environment, loaded during next build or next start. This is crucial for environments that are deployed to production.

Creating these files in your project directory allows Next.js to automatically load them based on the active environment. This organization helps keep your project tidy and your environment-specific settings clear and manageable.

Rules and Best Practices for Naming Environment Variables in Next.js

Next.js enforces certain conventions and offers best practices for naming environment variables, which help maintain security and functionality:

1. Prefix for Public Variables: Any environment variable that needs to be accessed from the client-side code must be prefixed with NEXT_PUBLIC_. This ensures that only variables explicitly marked as public are exposed to the browser, safeguarding your private data.

2. Consistent Naming Convention: Use UPPER_CASE and underscores to name your environment variables. This makes them easily identifiable in your code and separates them from regular variables.

3. Descriptive Names: Ensure that the names of your environment variables clearly describe their purpose. This increases code readability and maintainability.

1// Correct use of public and private variable names in Next.js
2const apiKey = process.env.API_KEY;  // Private, server-side only
3const publicUrl = process.env.NEXT_PUBLIC_WEBSITE_URL; // Public, accessible client-side

​

Securely Storing Sensitive Information Using Environment Variables

Storing sensitive information securely is crucial, and Next.js’s environment variable system supports this by:

1. Never Commit .env Files: Exclude your .env files from your version control system by adding them to your .gitignore file. This prevents sensitive data from being exposed publicly in repositories.

2. Use Environment-Specific Files: By using different files for local, development, and production environments (as mentioned above), you can tailor the visibility and accessibility of sensitive information as needed without the risk of exposing it inappropriately.

3. Server-Side Secrets: Keep sensitive data like database passwords or private API keys out of client-side code. Even with the public prefix system, it's best practice to handle secrets server-side whenever possible.

1// Example of adding .env files to .gitignore
2# .gitignore
3.env*
4!*.example

​

These practices when setting up and managing your environment variables in Next.js will enhance the security and efficiency of your application development workflow.

Accessing Environment Variables in Your Next.js Application

Next.js offers a flexible approach to handling environment variables, allowing you to access them both on the server-side and the client-side, but with important distinctions:

1. Server-Side Access: All environment variables in your .env files are available on the server-side through process.env. This access is unrestricted, meaning you can use both public and private variables as needed for operations like fetching data, connecting to databases, or calling external APIs.

2. Client-Side Access: Only variables prefixed with NEXT_PUBLIC_ are exposed to the browser. This ensures that sensitive information is kept secure and only information that needs to be publicly accessible is exposed. These variables are embedded during the build time and can be accessed anywhere in your client-side code.

1// Example of accessing an API key server-side and a public URL client-side
2export async function getServerSideProps() {
3    const apiKey = process.env.API_KEY;  // Accessed server-side
4    return { props: { apiKey } };
5}
6
7// In your component
8const apiUrl = process.env.NEXT_PUBLIC_API_URL;  // Accessed client-side

​

Tips for Accessing Environment Variables in Static and Server-Rendered Pages

When working with static and server-rendered pages in Next.js, consider these tips for effective environment variable usage:

1. Static Generation (getStaticProps/getStaticPaths): Environment variables are embedded at build time, so changes to environment variables after the build won't affect the already statically generated pages. Ensure that all necessary environment variables are correctly set before running the build command.

1export async function getStaticProps() {
2    const siteTitle = process.env.NEXT_PUBLIC_SITE_TITLE || 'Default Site Title';
3    return { props: { siteTitle } };
4}

​

2. Server-Side Rendering (getServerSideProps): Unlike static generation, environment variables in server-side rendering are read at runtime. This means any updates to your environment variables will be reflected on each request, making it suitable for dynamic content that depends on up-to-date configuration.

3. Consistent Values: Ensure consistency in your environment variables across all environments to prevent discrepancies in behavior. Use default values as a fallback in your code to handle missing or undefined environment variables gracefully.

Advanced Usage of Environment Variables

Setting Up Different Environments (Development, Test, Production)

Properly managing settings across multiple environments is crucial for maintaining the reliability and stability of your applications. Here’s how you can effectively differentiate and manage environment variables for development, test, and production environments in Next.js:

1. Environment-Specific .env Files: Utilize .env.local for your local development overrides, .env.development for development settings, .env.test for test configurations, and .env.production for production settings. This separation helps in maintaining clarity and prevents the accidental leakage of sensitive information from one environment to another.

2. Conditional Loading: Next.js automatically loads environment variables based on the NODE_ENV setting (development, production, test). Make sure to correctly set the NODE_ENV in your environment to match the intended .env files. For example, setting NODE_ENV=production will ensure that .env.production settings are loaded.

3. Scripting for Different Environments: In your package.json, you can set up scripts to explicitly define which environment should be considered during the build or runtime. This can help in avoiding common mistakes like using development settings in production.

1// Example package.json scripts for different environments
2"scripts": {
3    "dev": "next dev",
4    "build": "next build",
5    "start": "next start",
6    "test": "NODE_ENV=test next build"
7}

​

Dynamic Environment Variables with next.config.js

next.config.js allows for more dynamic configurations of your Next.js application, including modifying environment variables based on custom logic:

1. Environment Variable Injection: You can programmatically modify or add environment variables in next.config.js. This is useful when you need to derive environment variables from other variables or need to perform computations.

2. Expose Environment Variables to the Browser: If needed, you can explicitly choose which environment variables are exposed to the browser by configuring the publicRuntimeConfig or using webpack to define global constants.

1// Dynamic environment variables in next.config.js
2module.exports = {
3    env: {
4        CUSTOM_VAR: process.env.NODE_ENV === 'production' ? 'valueProd' : 'valueDev'
5    },
6    webpack(config, { isServer }) {
7        if (!isServer) {
8            config.plugins.push(new webpack.DefinePlugin({
9                'process.env.CUSTOM_VAR': JSON.stringify(process.env.CUSTOM_VAR)
10            }));
11        }
12        return config;
13    }
14}

​

Conclusion

Mastering the use of environment variables in Next.js is essential for building secure, scalable, and maintainable web applications. By understanding how to set up, manage, and access these variables effectively across different environments—be it local development, testing, or production—you can ensure that your application adapts seamlessly to varying conditions without compromising security. Adopt these practices to keep your application's configurations flexible and secure, setting a strong foundation for future growth and development.

Short on time? Speed things up with DhiWise!!

Tired of manually designing screens, coding on weekends, and technical debt? Let DhiWise handle it for you!

You can build an e-commerce store, healthcare app, portfolio, blogging website, social media or admin panel right away. Use our library of 40+ pre-built free templates to create your first application using DhiWise.