[← Back to Reviews Index](../Stewards%20Reviews%20Index.md)

# React Config Review — Azure-AI-RAG-CSharp-Semantic-Kernel-Functions

| Field | Value |
|---|---|
| Project | Azure-AI-RAG-CSharp-Semantic-Kernel-Functions |
| Steward | React Config Steward (RCFG) |
| Run Date | 2026-03-21 |
| React Project | `src/web` (Create React App, react-scripts 5.0.1) |
| Critical | 0 |
| Notable | 3 |
| Minor | 3 |
| Info | 3 |
| **Total** | **9** |

---

## 1. Configuration Architecture Overview

The React frontend is a standard Create React App (CRA) project located at `src/web`. It uses the `REACT_APP_*` environment variable prefix convention correctly. The application communicates with a C# ChatAPI backend via two fetch calls, both parameterized through a single environment variable `REACT_APP_API_HOST`.

There are two separate configuration paths for deployment:

- **Bicep (IaC) path:** `infra/app/web-app.bicep` sets `REACT_APP_API_HOST` as an Azure App Service application setting. However, because CRA bakes environment variables at build time (not runtime), this App Service setting has no effect on the bundled JavaScript. The deploy script (`infra/scripts/deploy_web.ps1`) correctly writes a `.env` file before building — this is the only mechanism that actually injects the variable.
- **Script (manual) path:** `deploy_web.ps1` receives `$apiURL` as a parameter, writes `REACT_APP_API_HOST=$apiURL` to `src/web/.env`, runs `npm install` and `npm run build`, then zips and deploys the artifact.

Overall configuration posture: **partially functional but fragile**. The working mechanism (deploy script writing `.env`) is not obvious, lacks a `.env.example`, and the Bicep App Service setting creates a false sense of runtime configurability that does not apply to CRA static bundles.

---

## 2. Environment Variables Assessment

### Variable Inventory

| Variable | Usage Location | Prefix Correct | Source |
|---|---|---|---|
| `REACT_APP_API_HOST` | `src/SupportAgent/Agent.js` lines 29, 48 | Yes (`REACT_APP_`) | Written by `deploy_web.ps1`; also in `README.md` as example |

### Findings

- **Only one environment variable is used.** This is appropriate for the application's minimal scope.
- **The `REACT_APP_` prefix is correct** for CRA. No Vite-style `VITE_` prefix issues.
- **No `.env.example` or `.env.sample` file exists.** The only documentation of the required variable is in `src/web/README.md` under "Usage", which shows `REACT_APP_API_HOST=http://127.0.0.1:8000`. This is informal documentation only and not machine-readable.
- **No environment-specific `.env` files exist:** `.env.development`, `.env.production`, `.env.staging` are all absent. CRA supports these natively and they are the recommended mechanism for per-environment defaults.
- **`.env` is correctly gitignored** in `src/web/.gitignore` (line 24). The `.env.local`, `.env.development.local`, `.env.test.local`, and `.env.production.local` variants are also listed. This is correct.
- **No `.env` file is committed to source control.** No credentials are exposed via git.

---

## 3. API Base URL Assessment

### Usage

`REACT_APP_API_HOST` is used twice in `src/web/src/SupportAgent/Agent.js`:

- Line 29: `fetch(process.env.REACT_APP_API_HOST + '/chat', ...)`
- Line 48: `fetch(process.env.REACT_APP_API_HOST + '/session')`

### Issues

- **No fallback/default value is provided.** If `REACT_APP_API_HOST` is undefined (e.g., developer clones the repo without creating a `.env`), the fetch URL becomes `undefined/chat`. This causes a silent runtime failure — the fetch will attempt to call `undefined/chat` which results in an error that is not surfaced to the user. There is no error handling in the `handlePrompt` or `handleSession` functions: network errors are uncaught.
- **No runtime validation.** There is no check at startup or render time that `REACT_APP_API_HOST` is defined and non-empty.
- **The Bicep App Service setting for `REACT_APP_API_HOST` (in `infra/app/web-app.bicep` line 27-29) is ineffective.** CRA bakes environment variables into the JavaScript bundle at build time via `process.env.REACT_APP_*`. Setting this variable in the Azure App Service application settings at runtime does nothing for a statically served CRA build. The only mechanism that works is writing the variable to `.env` before running `npm run build` — which `deploy_web.ps1` does correctly. The Bicep setting is misleading and should either be removed or replaced with a comment explaining the limitation.
- **The README documents `http://127.0.0.1:8000` as the example value.** This is appropriate for local development documentation. It does not appear hardcoded in source files.

---

## 4. Build-Time Configuration Assessment

### CRA Build-Time Model

CRA bundles `process.env.REACT_APP_*` values statically at build time. This means:

1. The variable must be present **before** `npm run build` runs.
2. Runtime injection (e.g., via Azure App Service settings or Kubernetes ConfigMaps) does not work for standard CRA builds.
3. Different builds are required for different environments (development, staging, production).

### Current State

- **Deploy script correctly writes `.env` before building.** `deploy_web.ps1` calls `Set-Content -Path "$nodeAppPath\.env" -Value "REACT_APP_API_HOST=$apiURL"` before invoking `npm run build`. This is the correct pattern for CRA builds.
- **No `.env.development` file exists.** Running `npm start` without a `.env` file means `REACT_APP_API_HOST` is undefined and the agent panel will silently fail to connect.
- **No `.env.production` file exists.** This is acceptable if the deploy script always supplies the value, but the absence increases risk of accidental deploys with undefined API URLs.
- **No feature flags are in use.** There are no `process.env.NODE_ENV === 'development'` conditionals or other feature flag patterns — this is not a concern for this application.
- **`dotenv` is listed in `dependencies` (not `devDependencies`) in `package.json` line 13.** CRA handles `.env` files natively via `react-scripts`; the explicit `dotenv` dependency is unnecessary and potentially confusing. It adds dead weight to the production bundle if inadvertently imported. It does not appear to be imported in any source file, so the risk is low, but it should be moved to `devDependencies` or removed.

---

## 5. Sensitive Values Assessment

- **No API keys or secrets are present in frontend environment variables or source files.** The only environment variable is the API host URL.
- **No Application Insights instrumentation keys, Azure AD client IDs, or other sensitive identifiers are hardcoded in source files.** The frontend has no direct Azure SDK integration.
- **The `dotenv` package in `dependencies` does not expose secrets**, but its presence is unnecessary (see Section 4).
- **The Bicep `web-app.bicep` sets `REACT_APP_API_HOST` as an App Service setting.** This value (`https://${appServiceNameAPI}.azurewebsites.net`) is the public API URL and is not sensitive. However, as noted, this setting is ineffective for the CRA build model.

Overall sensitive-value posture: **clean**. No secrets are exposed.

---

## 6. Findings

| Severity | ID | Title | File |
|---|---|---|---|
| 🟡 Notable | RCFG-ENVVAR-001 | No `.env.example` documenting required variables | `src/web/` |
| 🟡 Notable | RCFG-BUILD-001 | Bicep App Service `REACT_APP_API_HOST` setting is ineffective for CRA static builds | `infra/app/web-app.bicep` |
| 🟡 Notable | RCFG-APIURL-001 | No fallback or startup validation for `REACT_APP_API_HOST` — undefined URL causes silent failure | `src/web/src/SupportAgent/Agent.js` |
| 🟢 Minor | RCFG-ENVVAR-002 | No `.env.development` file — local development requires manual `.env` creation with no guidance | `src/web/` |
| 🟢 Minor | RCFG-ENVVAR-003 | `dotenv` package listed in `dependencies` instead of `devDependencies` | `src/web/package.json` |
| 🟢 Minor | RCFG-BUILD-002 | No `.env.production` default file — accidental build without API URL goes undetected | `src/web/` |
| ℹ️ Info | RCFG-ENVVAR-004 | `REACT_APP_` prefix used correctly for all environment variables | `src/web/src/SupportAgent/Agent.js` |
| ℹ️ Info | RCFG-ENVVAR-005 | `.env` and `.env.*.local` files are correctly gitignored | `src/web/.gitignore` |
| ℹ️ Info | RCFG-BUILD-003 | Deploy script correctly writes `.env` before building, ensuring CRA bakes the correct API URL | `infra/scripts/deploy_web.ps1` |

### Finding Details

#### RCFG-ENVVAR-001 — No `.env.example` documenting required variables
**Severity:** Notable

There is no `.env.example` or `.env.sample` file in `src/web/`. The only documentation of the required `REACT_APP_API_HOST` variable is informal prose in `src/web/README.md`. Without a committed example file, developers cloning the repository have no machine-readable reference for what variables to define, and tooling cannot validate completeness.

**Recommendation:** Create `src/web/.env.example` containing:

```
# API base URL for the ChatAPI backend.
# For local development: http://localhost:<port>
# Set this before running npm start or npm run build.
REACT_APP_API_HOST=http://localhost:8080
```

Commit this file to source control. The `.gitignore` already excludes `.env` but not `.env.example`, so no changes to `.gitignore` are needed.

---

#### RCFG-BUILD-001 — Bicep App Service `REACT_APP_API_HOST` setting is ineffective for CRA static builds
**Severity:** Notable

`infra/app/web-app.bicep` sets `REACT_APP_API_HOST` as an Azure App Service application setting (lines 27-29). This is a runtime environment variable injection mechanism. CRA builds compile all `process.env.REACT_APP_*` references into the static JavaScript bundle at build time — they cannot be changed at runtime without rebuilding. The App Service setting has no effect on the deployed bundle.

This is misleading: a developer or operator may believe they can update the API URL by changing the App Service setting, only to find the change has no effect.

**Recommendation:** Remove the `REACT_APP_API_HOST` app setting from `web-app.bicep` and add a comment explaining that CRA variables must be set at build time. Alternatively, migrate to a runtime configuration approach (e.g., serve a `config.js` from the static host, or use `window._env_` injection at container startup) if runtime reconfigurability is needed.

---

#### RCFG-APIURL-001 — No fallback or startup validation for `REACT_APP_API_HOST`
**Severity:** Notable

In `src/web/src/SupportAgent/Agent.js`, both fetch calls concatenate `process.env.REACT_APP_API_HOST` directly without a null/undefined check or fallback. If the variable is not defined at build time, `process.env.REACT_APP_API_HOST` evaluates to `undefined` and the fetch URL becomes the string `"undefined/chat"`. The fetch will fail with a network error, and no user-facing error message is shown — the chat panel simply never initializes.

**Recommendation:** Add a module-level guard or a defined fallback:

```js
const API_HOST = process.env.REACT_APP_API_HOST;
if (!API_HOST) {
  console.error('REACT_APP_API_HOST is not defined. Check your .env file.');
}
```

Additionally, add `.catch()` handlers to the `fetch` calls in `handlePrompt` and `handleSession` to surface network errors to the user rather than silently failing.

---

#### RCFG-ENVVAR-002 — No `.env.development` file
**Severity:** Minor

CRA natively loads `.env.development` when running `npm start`. Without this file, developers must manually create a `.env` file with the correct `REACT_APP_API_HOST` value before they can run the application locally. There is no automated default and no immediate error to guide them.

**Recommendation:** Create `src/web/.env.development` with a sensible local default:

```
REACT_APP_API_HOST=http://localhost:8080
```

Add `# Developer default — override by creating .env.local` as a comment. This file should be committed (it contains no secrets, only a localhost URL). Update `.gitignore` if needed — currently `.env.development` is not excluded (only `.env.development.local` is).

---

#### RCFG-ENVVAR-003 — `dotenv` package in `dependencies` instead of `devDependencies`
**Severity:** Minor

`package.json` lists `dotenv` as a runtime dependency (line 13). CRA handles `.env` files natively through `react-scripts` and does not require an explicit `dotenv` package. The package does not appear to be imported in any source file. Including it in `dependencies` rather than `devDependencies` (or removing it entirely) is unnecessary and could mislead developers into thinking it is actively used.

**Recommendation:** Remove `dotenv` from `dependencies`. If it is genuinely needed for any tooling script, move it to `devDependencies`. Verify no source file imports it before removing.

---

#### RCFG-BUILD-002 — No `.env.production` default file
**Severity:** Minor

There is no `.env.production` file in `src/web/`. CRA loads this file when running `npm run build`. Without it, if `npm run build` is run without the deploy script (e.g., in a CI pipeline that does not call `deploy_web.ps1`), `REACT_APP_API_HOST` will be undefined and the build will silently produce a broken artifact.

**Recommendation:** Create `src/web/.env.production` as a placeholder with a comment:

```
# Production API URL is injected by deploy_web.ps1 before running npm run build.
# Do not set REACT_APP_API_HOST here — it must be supplied by the deploy pipeline.
# REACT_APP_API_HOST=
```

Committing this file documents the intent and serves as a reminder for future CI pipeline authors.

---

#### RCFG-ENVVAR-004 — `REACT_APP_` prefix used correctly
**Severity:** Info

All environment variable references in source code use the correct `REACT_APP_` prefix required by CRA. No Vite-style or non-prefixed variables are present.

---

#### RCFG-ENVVAR-005 — `.env` and `.env.*.local` files correctly gitignored
**Severity:** Info

`src/web/.gitignore` correctly excludes `.env`, `.env.local`, `.env.development.local`, `.env.test.local`, and `.env.production.local`. No `.env` files with real values are committed to source control.

---

#### RCFG-BUILD-003 — Deploy script correctly writes `.env` before building
**Severity:** Info

`infra/scripts/deploy_web.ps1` writes `REACT_APP_API_HOST=$apiURL` to `src/web/.env` before invoking `npm install` and `npm run build`. This is the correct pattern for CRA builds and ensures the production API URL is baked into the bundle. The `$apiURL` parameter is passed in from the caller, providing a clean separation between the build script and the environment-specific value.

---

## 7. Recommended Improvements

| Finding | Recommended Action | Priority |
|---|---|---|
| RCFG-ENVVAR-001 | Create `src/web/.env.example` documenting `REACT_APP_API_HOST` and commit it | High |
| RCFG-BUILD-001 | Remove ineffective `REACT_APP_API_HOST` App Service setting from `web-app.bicep`; add explanatory comment | High |
| RCFG-APIURL-001 | Add undefined check for `REACT_APP_API_HOST` at module level; add `.catch()` handlers to fetch calls | High |
| RCFG-ENVVAR-002 | Create `src/web/.env.development` with localhost default for developer convenience | Medium |
| RCFG-ENVVAR-003 | Remove or move `dotenv` from `dependencies` to `devDependencies` (or remove entirely) | Low |
| RCFG-BUILD-002 | Create `src/web/.env.production` as a placeholder with explanatory comments | Low |

---

## Footer

This review is based on static analysis of source files and configuration artifacts. No runtime environment was executed, no build was performed, and no network requests were made. Findings reflect the state of the codebase at the time of the review run (2026-03-21) and may not reflect runtime behavior.

Generated by: **React Config Steward** (`react-config-steward.md`) — PREFIX `RCFG`