Environment Variables and Configs in React

Managing environment-specific variables is a critical part of building robust, secure, and scalable React applications. Whether you’re connecting to different APIs, enabling feature flags, or handling keys and secrets, understanding environment variables is essential.

This module dives deep into React environment variables, how they work, how to manage different configurations across environments (development, staging, production), and best practices for keeping your secrets secure.

---

Table of Contents

1. What Are Environment Variables?
2. Why Use Environment Variables in React?
3. Using Environment Variables in Create React App (CRA)
4. Using Environment Variables in Vite
5. Environment Variable Naming Conventions
6. Managing Multiple Environments
7. Using .env Files Securely
8. Injecting Environment Variables at Build Time
9. Common Pitfalls and Gotchas
10. Best Practices
11. Conclusion

---

1. What Are Environment Variables?

Environment variables are key-value pairs that define configuration values outside the source code. These allow you to dynamically change behavior of your app depending on the environment it’s running in (e.g., development, production).

Examples:

• API endpoints
• API keys
• Feature flags
• Analytics toggles

---

2. Why Use Environment Variables in React?

• Security: Avoid hardcoding secrets and keys in source code.
• Flexibility: Easily switch between dev, staging, and prod configurations.
• Separation of concerns: Keep configuration out of code logic.
• Build-time injection: React compiles variables during build.

---

3. Using Environment Variables in Create React App (CRA)

CRA supports .env files out of the box.

Steps:

1. Create a .env file in the root of your project.
2. Prefix all environment variables with REACT_APP_.

REACT_APP_API_URL=https://api.dev.com
REACT_APP_ANALYTICS_KEY=abcdef1234

In your code:

const apiUrl = process.env.REACT_APP_API_URL;

CRA loads .env, .env.local, .env.development, and .env.production depending on the script being run.

---

4. Using Environment Variables in Vite

Vite supports .env files similarly, but requires variables to be prefixed with VITE_.

VITE_API_URL=https://api.vite.dev

Access it like this:

const apiUrl = import.meta.env.VITE_API_URL;

Vite also automatically replaces these at build time.

---

5. Environment Variable Naming Conventions

Tool	Prefix Required	Access Syntax
CRA	REACT_APP_	process.env.REACT_APP_*
Vite	VITE_	import.meta.env.VITE_*
Next.js	NEXT_PUBLIC_	process.env.NEXT_PUBLIC_* (for public)

This prefixing helps ensure that only explicitly whitelisted variables are exposed to the frontend.

---

6. Managing Multiple Environments

To handle separate variables for different stages:

• .env – base variables
• .env.development – dev-specific variables
• .env.production – production-specific variables
• .env.local – machine-specific secrets (should be gitignored)

CRA and Vite automatically detect and use these based on NODE_ENV.

---

7. Using .env Files Securely

• Never commit secrets to Git. Always add .env* files to .gitignore.
• Store .env.example in version control to share variable structure with your team.
• Use tools like dotenv-cli, direnv, or env-cmd to manage environments locally or during deployment.

---

8. Injecting Environment Variables at Build Time

Both CRA and Vite replace environment variables at build time. That means you can’t change them dynamically at runtime unless you:

• Use a backend proxy or gateway
• Fetch them from an API on app load

This is important to note if you’re deploying to a static host like Vercel or Netlify.

---

9. Common Pitfalls and Gotchas

• Using a variable without the required prefix (e.g., no REACT_APP_)
• Expecting variables to change without rebuilding
• Forgetting to restart the dev server after modifying .env
• Committing sensitive .env files accidentally

---

10. Best Practices

• Use REACT_APP_ or VITE_ prefixes strictly.
• Store only non-sensitive frontend-exposed variables in the client.
• Use .env.local for machine-specific overrides.
• Maintain a .env.example for onboarding and CI/CD.
• Document the use of each variable clearly.

---

11. Conclusion

Environment variables are a foundational tool for managing app configurations securely and efficiently. Whether you’re using CRA, Vite, or any modern React framework, understanding how these variables work — and how to manage them across environments — is essential for scalable and secure development.