Fix error loading .env.local into ALL builds, regardless of environment (#4621)

# Description and Motivation
<!--- bulleted, high level items. use keywords (eg "closes #144" or
"fixes #4323") -->

This pull request resolves an issue where Vite's default behavior of
loading .env.local caused local development environment variables to
inadvertently affect other build processes. The solution involves
renaming the local environment file to .env.localhost and systematically
updating all related scripts, code, and documentation. This change
ensures a clear separation of local development configurations from
other environments, leading to more robust and predictable builds.

Highlights
- Environment Configuration Refinement: Renamed frontend/.env.local to
frontend/.env.localhost to prevent unintended loading by Vite in
non-local builds, ensuring environment variable isolation.
- Script and Code Alignment: Updated npm scripts in package.json and
internal code references in DataFetcher.ts and Environment.ts to reflect
the new localhost naming convention.
- Documentation Update: Modified README.md to guide developers on using
the new npm run localhost command and the .env.localhost file.
- Git Ignore Enhancement: Added frontend/.env.local to .gitignore to
prevent accidental commits of the old, problematic file name.

## Has this been tested? How?

need to merge and deploy to full test; success will be demonstrated when
network calls from the PROD website no longer route to
`dev.healthequitytracker.org` as they are currently. This was because
the base API en variable was set in the now deprecated `.env.local`
file, the assumption being that file loaded ONLY in local development.
However, Vite loads that file whenever it's present, and merges with
other loaded files, so this file was being loaded in deploy preview and
dev environments, but ALSO in prod making the data_server URL incorrect

## Screenshots (if appropriate)

ERROR
<img width="1568" height="516" alt="image"
src="https://github.com/user-attachments/assets/46665166-9e1e-4fde-a4ad-5d519ee8dad7"
/>


## Types of changes

(leave all that apply)

- Bug fix
- Refactor / chore

## New frontend preview link is below in the Netlify comment 😎

Author: benhammondmusic

.gitignore

@@ -25,6 +25,7 @@ config/.terraform.lock.hcl
 
 # Environment Files
 .env.secrets
+/frontend/.env.local
 /frontend_server/.env.local
 /frontend_server/.env.development
 /scripts/.env.secrets

README.md

@@ -119,7 +119,7 @@ Note: If you are using VSCode or one of its forks, ensure you install the recomm
 1. While still in the `health-equity-tracker/frontend/` folder, run
 
    ```bash
-   npm run local
+   npm run localhost
    ```
 
 2. In your browser, visit <http://localhost:3000>
@@ -267,7 +267,7 @@ The frontend uses multiple environments to assist with development, testing, and
 
 | Environment | .env File | Frontend Deployment | Backend GCP Project | Description |
 |-------------|-----------|---------------------|---------------------|-------------|
-| Local Development | `.env.local` (create from template) | Local machine's <http://localhost:3000> | het-infra-test | For developer workstations. |
+| Local Development | `.env.localhost` | Local machine's <http://localhost:3000> | het-infra-test | For developer workstations. |
 | PR Preview | `.env.deploy_preview` | Netlify PR Preview; URL in GitHub PR comment | het-infra-test | Temporary deployments for pull request reviews. |
 | Development | `.env.dev` | dev.healthequitytracker.org | het-infra-test | Stable environment for testing features before production. |
 | Production | `.env.production` | healthequitytracker.org | het-infra-prod | Live environment for end users. |

frontend/.env.local frontend/.env.localhostfrontend/.env.local renamed to frontend/.env.localhost

@@ -4,7 +4,7 @@
 # Configuration for local development environment with connection to het-infra-test backend
 
 # Deployment context identifier
-VITE_DEPLOY_CONTEXT=local
+VITE_DEPLOY_CONTEXT=localhost
 
 # API configuration
 # Base URL for API requests in local development

frontend/package.json

@@ -77,14 +77,14 @@
 	},
 	"scripts": {
 		"build:deploy_preview": "env-cmd -f .env.deploy_preview npm run build",
-		"build:local": "env-cmd -f .env.local npm run build",
+		"build:localhost": "env-cmd -f .env.localhost npm run build",
 		"build:prod": "env-cmd -f .env.prod npm run build",
 		"build:dev": "env-cmd -f .env.dev npm run build",
 		"build": "vite build",
 		"cleanup": "npx @biomejs/biome check --write  --unsafe ./src",
 		"cspell": "cspell '../**/*.{ts,tsx,css,md,py}' --no-progress --no-must-find-files --gitignore",
-		"dev": "npm run local",
-		"local": "env-cmd -f .env.local npm run start -- --host & npm run tsc:watch",
+		"dev": "npm run localhost",
+		"localhost": "env-cmd -f .env.localhost npm run start -- --host & npm run tsc:watch",
 		"e2e": "npx playwright install chromium && npx playwright test --project=E2E_NIGHTLY --workers 4",
 		"e2e-dev": "npx playwright install chromium && cross-env E2E_BASE_URL=https://dev.healthequitytracker.org npx playwright test --project=E2E_NIGHTLY --workers 5",
 		"e2e-prod": "npx playwright install chromium && cross-env E2E_BASE_URL=https://healthequitytracker.org npx playwright test --project=E2E_NIGHTLY --workers 5",
@@ -95,9 +95,9 @@
 		"e2e:new": "npm run e2e-new",
 		"e2e:nightly": "npx playwright install chromium && npx playwright test --project=E2E_NIGHTLY --workers 2",
 		"e2e:watch": "npx playwright install chromium && cross-env PWTEST_WATCH=1 npx playwright test --project=E2E_NIGHTLY --workers 2",
-		"preview": "npm run build:local && vite preview",
+		"preview": "npm run build:localhost && vite preview",
 		"start:deploy_preview": "env-cmd -f .env.deploy_preview npm run start",
-		"start:local": "env-cmd -f .env.local npm run start",
+		"start:localhost": "env-cmd -f .env.localhost npm run start",
 		"start": "vite",
 		"test:coverage": "vitest run --coverage",
 		"test:watch": "vitest watch",
@@ -121,4 +121,4 @@
 			"last 1 safari version"
 		]
 	}
-}
+}

frontend/src/data/loading/DataFetcher.ts

@@ -42,7 +42,7 @@ export class ApiDataFetcher implements DataFetcher {
    */
   private shouldFetchAsStaticFile(fileName: string) {
     return (
-      (this.environment.deployContext === 'local' &&
+      (this.environment.deployContext === 'localhost' &&
         !this.environment.getBaseApiUrl()) ||
       this.environment.forceFetchDatasetAsStaticFile(fileName)
     )

frontend/src/utils/Environment.ts

@@ -1,22 +1,12 @@
-type DeployContext =
-  // Production environment in GCP
-  | 'prod'
-
-  // The "dev" GCP environment that gets auto-deployed from main branch to dev.healthequitytracker.org
-  | 'dev'
-
-  // Deploy previews. Currently, all netlify deploys are considered deploy
-  // previews.
-  | 'deploy_preview'
-
-  // When running npm run dev, or when running Docker locally
-  | 'local'
-
-  // Unit or integration tests
-  | 'test'
-
-  // Unknown deploy context. This generally shouldn't happen.
-  | 'unknown'
+const DEPLOY_CONTEXTS = [
+  'prod', // Production environment in GCP (healthequitytracker.org)
+  'dev', // Dev environment, auto-deployed from main (dev.healthequitytracker.org)
+  'deploy_preview', // Netlify PR previews
+  'localhost', // Local development
+  'test', // Unit/integration tests
+  'unknown', // Fallback — should not occur in practice
+] as const
+type DeployContext = (typeof DEPLOY_CONTEXTS)[number]
 
 export interface Environment {
   /** The context the frontend is currently running in. */
@@ -39,10 +29,8 @@ export interface Environment {
 
   /**
    * Whether to fetch the dataset as a static file from the public/tmp/
-   * directory.
-   *
-   * This should only be used for local development or in-progress datasets. In
-   * production, all datasets should be fetched from the data server.
+   * directory. Should only be used for local development or in-progress
+   * datasets not yet on the data server.
    */
   forceFetchDatasetAsStaticFile: (fileName: string) => boolean
 }
@@ -67,9 +55,11 @@ class HetEnvironment implements Environment {
   }
 
   getBaseApiUrl() {
-    // If the API url isn't provided, requests are relative to current domain.
+    // Empty string means API calls are relative to the current domain.
+    // NOTE: Vite always loads .env.local regardless of mode — use .env.localhost
+    // for local dev to avoid contaminating prod builds.
     const apiBaseUrl = this.getEnvVariable('BASE_API_URL')
-    if (!apiBaseUrl && this.deployContext === 'local') {
+    if (!apiBaseUrl && this.deployContext === 'localhost') {
       console.warn(
         '\n\n.ENV MISSING\n\n\nBASE_API_URL environment variable is not set. See the repo README for more information.',
       )
@@ -95,14 +85,9 @@ function getDeployContext(): DeployContext {
     return 'test'
   }
 
-  if (import.meta.env.NODE_ENV === 'local') {
-    return 'local'
-  }
-
   const deployContextVar = import.meta.env.VITE_DEPLOY_CONTEXT
   if (deployContextVar) {
-    const expectedContexts = ['prod', 'dev', 'deploy_preview', 'local']
-    if (!expectedContexts.includes(deployContextVar)) {
+    if (!DEPLOY_CONTEXTS.includes(deployContextVar as DeployContext)) {
       throw new Error('Invalid value for deploy context environment variable')
     }
     return deployContextVar as DeployContext