Comprehensive Guide to Environment Variables in Create React App: REACT_APP_ Prefix and .env File Priorities

Keywords: Create React App | Environment Variables | REACT_APP Prefix | .env Files | Configuration Priorities

Abstract: This technical article provides an in-depth analysis of environment variable configuration in Create React App, focusing on the mandatory REACT_APP_ prefix requirement and the loading priorities of different .env file types. Through practical code examples and problem-solving approaches, it details how to effectively manage environment variables across development and production environments, avoiding common configuration pitfalls and ensuring proper parameter reading in various deployment scenarios.

Core Mechanism of Environment Variables in Create React App

Create React App (CRA) implements a standardized approach to environment variable management for React applications. Environment variables are embedded during the build process, becoming integral parts of the final bundle rather than being dynamically read at runtime. This architectural choice stems from CRA's generation of static HTML/CSS/JS resource bundles that cannot access server environments during client-side execution.

Security Imperative of REACT_APP_ Prefix

CRA enforces the requirement that all custom environment variables must begin with REACT_APP_, a crucial design decision for security purposes. The system filters out variables not starting with this prefix to prevent accidental exposure of sensitive information that might exist on the machine, such as private keys or other confidential data.

Consider this incorrect configuration example:

// Incorrect configuration in .env.development file
API_URL=http://localhost:3000/api
CALLBACK_URL=http://localhost:3005/callback

The above configuration will be completely ignored by CRA. The correct approach is:

// Correct configuration in .env.development file
REACT_APP_API_URL=http://localhost:3000/api
REACT_APP_CALLBACK_URL=http://localhost:3005/callback

.env File Types and Loading Priorities

CRA supports multiple .env file types, each with specific use cases and loading sequences. Understanding these file priorities is essential for proper multi-environment deployment configuration.

In development environment (using npm start), file loading priority from highest to lowest is:

.env.development.local > .env.local > .env.development > .env

In production build environment (using npm run build), the priority becomes:

.env.production.local > .env.local > .env.production > .env

Practical Implementation and Code Examples

Once environment variables are properly configured, they can be accessed in JavaScript code through the process.env object. Here's a comprehensive example:

// Content of .env.development file
REACT_APP_API_BASE_URL=https://api.dev.example.com
REACT_APP_DEBUG_MODE=true
REACT_APP_VERSION=1.0.0

Using environment variables in React components:

import React from 'react';

const AppConfig = () => {
  return (
    <div>
      <p>Current API Endpoint: {process.env.REACT_APP_API_BASE_URL}</p>
      <p>Debug Mode: {process.env.REACT_APP_DEBUG_MODE}</p>
      <p>Application Version: {process.env.REACT_APP_VERSION}</p>
      <p>Runtime Environment: {process.env.NODE_ENV}</p>
    </div>
  );
};

export default AppConfig;

Common Issues and Solutions

Developers frequently encounter several issues when configuring environment variables:

Issue 1: Variables Not Recognized
Ensure all custom variables start with REACT_APP_, which is the most common configuration mistake.

Issue 2: Incorrect File Location
.env files must be placed in the project root directory, not within the src folder. Incorrect file placement prevents proper variable loading.

Issue 3: Server Not Restarted
After modifying .env files, the development server must be restarted for changes to take effect, as environment variables are read and cached during server startup.

Using Environment Variables in HTML

Beyond JavaScript code, environment variables can also be utilized in the public/index.html file. This is particularly useful for dynamically setting page titles or other HTML attributes:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>%REACT_APP_WEBSITE_NAME%</title>
    <meta name="description" content="%REACT_APP_SITE_DESCRIPTION%" />
</head>
<body>
    <div id="root"></div>
</body>
</html>

Multi-Environment Configuration Best Practices

For complex multi-environment deployments, the following file structure is recommended:

/.env                    # Default configuration
/.env.development       # Development environment specific configuration
/.env.production        # Production environment specific configuration  
/.env.staging           # Staging environment configuration
/.env.local             # Local override configuration (not committed to version control)

Each environment file can contain variables specific to that environment:

// .env.development
REACT_APP_API_URL=https://dev-api.example.com
REACT_APP_LOG_LEVEL=debug

// .env.production  
REACT_APP_API_URL=https://api.example.com
REACT_APP_LOG_LEVEL=error

Security Considerations

It's crucial to emphasize that environment variables are embedded into the application during build time, meaning they appear in the final bundled files. Therefore:

Do not store genuine secrets (such as database passwords, private keys) in environment variables
For sensitive data, consider using backend APIs or dedicated configuration services
Regularly review environment variables to ensure no sensitive information is accidentally exposed

By following these best practices, developers can fully leverage CRA's environment variable capabilities while ensuring application security and maintainability.

Copyright Notice: All rights in this article are reserved by the operators of DevGex. Reasonable sharing and citation are welcome; any reproduction, excerpting, or re-publication without prior permission is prohibited.