Fixing Next.js Undefined ENV Variables in Production Build

Understanding the Error

When building applications with Next.js, environment variables allow you to insert values that can change based on the environment your app is running in. If you’ve run into an error where your environment variables are undefined in a production build, yet work fine in development, it usually stems from Next.js’s built-in environment loading mechanism, which distinguishes between public and server-side variables, or an improper setup in your production environment.

Applying the Solution

To resolve the undefined environment variables issue in Next.js for your production build, you need to ensure that variables are loaded correctly and accessible where they’re needed. Next.js provides different prefixes and files to handle environment variables, and making sure these are correctly set up is key to solving your problem. Every public environment variable should be prefixed with NEXT_PUBLIC_ to ensure that they are embedded into the build and can be accessed in the browser. Server-side secrets, on the other hand, should not have this prefix and must be kept in secure storage accessible to the server environment. Additionally, variables for local development are usually placed in a .env.local file, but for production, you typically use a different method like setting variables in your hosting provider’s dashboard or through a CI/CD pipeline.

Server-Side Rendering and API Routes

For pages with Server-Side Rendering (SSR) or API Routes, you don’t need to worry about prefixing your environment variables. However, you do need to ensure they are properly loaded in your production environment. Access to process.env on the server is similar to how you would access environment variables in a Node.js application, so you don’t need the NEXT_PUBLIC_ prefix for server-side code.

Using .env Files

Next.js supports loading environment variables from .env files. During your local development, variables often go in a .env.local file. When moving to production, you might have a .env.production file. It’s crucial that these files or their variables are available in your build environment, as Next.js will load different .env files based on the command or script you’re running.

Example Code

In the following example, we create a basic Next.js application that logs an environment variable on both the server and the client side, to demonstrate how to properly configure and use them.

// pages/index.js
export default function Home() {
  return (
     <div>
        <h3>Public variable: {process.env.NEXT_PUBLIC_MY_VARIABLE}</h3>
        <h3>Server variable (check server log): `Your secret is safe.`</h3>
     </div>
);
}

export async function getServerSideProps() {
  console.log('Server-side secret:', process.env.MY_SECRET_VARIABLE);
  return { props: {} };
}

You’ll need to place public variable in your .env.local or production environment variable file with the prefix and a private variable:

NEXT_PUBLIC_MY_VARIABLE=publicvalue
MY_SECRET_VARIABLE=supersecret

In a production environment, you’ll configure these variables in alignment with the hosting service you are using. For example, with Vercel, you would set them in your project’s settings under Environment Variables. When you deploy your app, these variables will be included in the build, ensuring operation is identical to your local development experience.

Conclusion

By understanding how Next.js handles environment variables for production and development environments, properly prefixing public variables, making server-side secrets accessible where they’re needed, and utilizing .env files accordingly, you can successfully troubleshoot and resolve situations where environment variables are undefined in your Next.js production build.