feat: Add environment variable validation for development mode

[meet1785]

Description

This PR adds a new feature to help developers catch common mistakes with environment variables during development. The feature automatically scans source code for process.env.REACT_APP_* references and validates that they are defined in .env files or the environment.

Motivation

Currently, when developers reference undefined environment variables in Create React App, they receive no warning until runtime, leading to subtle bugs where process.env.REACT_APP_SOMETHING is undefined. This feature provides immediate feedback during development to catch these issues early.

Key Features

• ✅ Automatically detects all REACT_APP_* environment variable references in JavaScript and TypeScript files
• ✅ Warns developers when they reference undefined environment variables
• ✅ Provides intelligent typo detection with suggestions using Levenshtein distance algorithm (e.g., suggests REACT_APP_API_URL for REACT_APP_API_ULR)
• ✅ Only runs in development mode (npm start) - does not affect production builds
• ✅ Excludes test files from validation since they often use mocked values
• ✅ Non-blocking - never prevents the dev server from starting
• ✅ Can be disabled by setting DISABLE_ENV_CHECK=true

Example Output

When a developer references undefined variables:

Warning: The following environment variables are referenced in your code but not defined:

  REACT_APP_API_URL
    Did you mean REACT_APP_API_URI?

To fix this, add the missing variables to your .env file or set them in your environment.
For example, add this line to your .env file:

  REACT_APP_API_URL=your_value_here

Learn more: https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables

To disable this check, set DISABLE_ENV_CHECK=true in your environment.

Changes Made

1. Created checkEnvVariables utility in packages/react-dev-utils/

• Implements fuzzy matching for typo suggestions using Levenshtein distance
• Scans source files using globby
• Provides clear, actionable error messages with chalk formatting

2. Integrated validation into npm start workflow

• Added call to checkEnvVariables in packages/react-scripts/scripts/start.js
• Runs after required file checks but before webpack compilation
• Non-blocking - always returns true to avoid breaking builds

3. Added comprehensive test suite

• 11 test cases covering all functionality
• Tests typo detection, multiple variables, TypeScript support, error handling, etc.
• All tests passing ✓

4. Updated documentation

• Added "Environment Variable Validation" section to adding-custom-environment-variables.md
• Updated react-dev-utils/README.md with API documentation and usage examples
• Added feature to package.json files list

Testing

All tests pass:

$ cd packages/react-dev-utils && npm test -- checkEnvVariables.test.js
PASS  __tests__/checkEnvVariables.test.js
  checkEnvVariables
    ✓ should not warn when all referenced variables are defined (11 ms)
    ✓ should warn when referenced variables are undefined (2 ms)
    ✓ should suggest similar variable names for typos (1 ms)
    ✓ should handle multiple undefined variables (1 ms)
    ✓ should skip check when NODE_ENV is not development (1 ms)
    ✓ should skip check when DISABLE_ENV_CHECK is true
    ✓ should handle files in subdirectories (1 ms)
    ✓ should handle TypeScript files (1 ms)
    ✓ should ignore test files (2 ms)
    ✓ should handle errors gracefully (1 ms)
    ✓ should handle empty directory (2 ms)

Test Suites: 1 passed, 1 total
Tests:       11 passed, 11 total

End-to-end testing confirmed:

• Warns when variables are undefined
• Suggests corrections for typos
• Silent when all variables are defined
• Can be disabled with DISABLE_ENV_CHECK=true

Benefits

• Reduces debugging time by catching environment variable mistakes early
• Improves developer experience with helpful error messages and suggestions
• Prevents production bugs caused by undefined environment variables
• Maintains backward compatibility - optional and non-breaking
• Follows CRA philosophy of providing helpful error messages and automatic problem detection

Backward Compatibility

This feature is:

• ✅ Non-breaking - only adds warnings, never errors
• ✅ Optional - can be disabled with DISABLE_ENV_CHECK=true
• ✅ Development-only - no impact on production builds
• ✅ Respectful of existing workflows - doesn't require any changes to existing code

Checklist

• Tests added and passing
• Documentation updated
• Code follows existing style and conventions
• Feature is non-breaking and optional
• Works with both JavaScript and TypeScript
• Handles edge cases gracefully

Related Issues

This addresses a common pain point mentioned in various issues where developers struggle to debug undefined environment variables. The feature provides immediate, actionable feedback similar to other CRA developer experience improvements.

[meta-cla]

Hi @meet1785!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!