Environment variables play a crucial role in web development, especially in configuring sensitive information such as API keys, database URLs, and other configuration settings. If your environment variables are showing up as undefined in your Next.js app, it can disrupt functionality. This issue typically arises from incorrect naming, file placement, or not restarting the server.

In Next.js, handling these variables correctly ensures the smooth functioning of your application. This article will guide you through setting up environment variables in Next.js and troubleshooting common issues.

Setting Up Environment Variables in Next.js

1. Creating the .env File:

To store your environment variables, create a .env file in the root directory of your Next.js project.

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=mongodb://localhost:27017/my_database

2. Prefixing Environment Variables:

Next.js distinguishes between server-side and client-side environment variables. For variables to be accessible on the client side, they must be prefixed with NEXT_PUBLIC_.

3. Accessing Environment Variables:

Server-side:

To use environment variables in your code, reference them via process.env.

// pages/api/data.js

export default function handler(req, res) {
    const dbUrl = process.env.DATABASE_URL;
    
    // Use dbUrl for database connection logic
    res.status(200).json({ message: 'Connected to database' });
}

Client-side:

For client-side usage, ensure the variable is prefixed with NEXT_PUBLIC_:

// components/ApiComponent.js
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

function ApiComponent() {
    return <div>API URL: {apiUrl}</div>;
}

export default ApiComponent;

Common Issues and Solutions

Issue 1: Environment Variables Are Undefined

• Check the .env File Location: Ensure that your .env file is in the root directory of your Next.js project. Variables defined elsewhere will not be recognized.
• Restart the Development Server: Next.js reads environment variables when the server starts. If you add or modify variables, restart the server:

npm run dev
 or
yarn dev

• Verify Variable Names: Double-check the spelling and prefix of your environment variables. Client-side variables must start with NEXT_PUBLIC_.
• Rebuild the Project: For production environments, rebuild your project after making changes to environment variables:

npm run build
npm start
 or
yarn build
yarn start

Issue 2: Environment Variables Not Working in Production

• Check Deployment Settings: Ensure that your environment variables are correctly set in your deployment environment. Different platforms have unique methods for configuring environment variables.
• Verify Build Process: Confirm that your deployment process includes the .env file and properly sets up environment variables during the build stage.

Best Practices to Avoid

1. Use .env.local for Local Development

Next.js supports different environment files for various stages:

• .env.local for local development
• .env.development for development builds
• .env.production for production builds
• Using .env.local helps keep your local settings separate from other environments.

2. Secure Sensitive Information

Exclude your .env files from version control to prevent sensitive information from being exposed.

// .gitignore
.env
.env.local

3. Validate Environment Variables

To ensure all required environment variables are correctly set, use a validation library like env-schema or joi:

// lib/env.js
import { cleanEnv, str, url } from 'envalid';

function validateEnv() {
  cleanEnv(process.env, {
     NEXT_PUBLIC_API_URL: url(),
     DATABASE_URL: str(),
  });
}

export default validateEnv;

4. Use Environment Variable Management Tools

For advanced management, consider tools like dotenv-cli to load environment variables from specific files:

npm install dotenv-cli

Then, run your application with the specified environment:

dotenv -e .env.local -- next dev

Conclusion

Managing environment variables is essential for the configuration and security of your Next.js application. By following the guidelines and troubleshooting steps provided, you can ensure that your environment variables are properly set up and functioning. Remember to secure your sensitive data and validate your variables to maintain a robust and secure application setup.