🔐 How to Set Up Environment Variables in Next.js (with Examples)

Introduction

Environment variables are essential when working on any modern web application. Whether it’s storing your API keys, base URLs, or secret tokens — environment variables help you securely manage configuration without hardcoding sensitive data.

In this tutorial, you’ll learn how to use environment variables in a Next.js project, the different .env files you can use, and best practices to avoid common pitfalls.

🧾 What Are Environment Variables?

Environment variables are key-value pairs used to configure apps without exposing sensitive values in your source code. In Next.js, they help you define things like:

• API base URLs
• Secret keys (for backend-only use)
• Public config (available in the browser)

⚙️ Step-by-Step: Setting Up Env Variables in Next.js

1. Create Your .env File

At the root of your project, create a .env.local file:

touch .env.local

Now add your variables:

NEXT_PUBLIC_API_URL=https://api.example.com
SECRET_KEY=my-secret-key

💡 Prefix variables with NEXT_PUBLIC_ if you want them accessible on the client side.

2. Use Environment Variables in Your Code

In pages/index.js:

export default function Home() {
  console.log(process.env.NEXT_PUBLIC_API_URL);

  return (
    <div>
      <h1>Welcome</h1>
      <p>API: {process.env.NEXT_PUBLIC_API_URL}</p>
    </div>
  );
}

For backend-only values like SECRET_KEY, use them only in getServerSideProps, API routes, or server-side functions.

3. Add to .gitignore

Never commit your env files to Git:

# .gitignore
.env.local

4. Access in next.config.js (Optional)

If needed, you can load env variables into next.config.js:

module.exports = {
  env: {
    CUSTOM_VAR: process.env.CUSTOM_VAR,
  },
};

But this is only needed if you’re using env vars at build time.

🔄 Different .env File Types

🧯 Common Mistakes & Fixes

1. Variable is undefined?
   • Restart your server after adding env variables.
2. Forget to prefix with NEXT_PUBLIC_?
   • Env vars won’t be available on the client side.
3. Using env variables in the browser that shouldn’t be?
   • Never expose secrets with NEXT_PUBLIC_.

❓ FAQs

1. Do I need to restart the server after changing .env.local?

Yes! Next.js only reads env variables at startup.

2. What’s the difference between .env and .env.local?

.env is for defaults. .env.local overrides it and is not meant to be committed.

3. Can I use environment variables in static pages?

Yes, but only if they’re available at build time.

4. Is it safe to expose NEXT_PUBLIC_* variables?

Yes, but only if they’re meant to be public (like public API endpoints, not secret keys).

5. Can I use dotenv manually in Next.js?

Not needed—Next.js has built-in dotenv support out of the box.

✅ Conclusion

Using environment variables in Next.js is simple, secure, and powerful — as long as you follow the best practices. Keep your secrets server-side, prefix client-side variables with NEXT_PUBLIC_, and make sure not to commit your .env.local files to version control.

Whether you’re integrating APIs or deploying to production, mastering env vars is a small step with a big impact.

#nextjs #env #javascript #webdevelopment #beginners #frontend