Environment Configuration & Deployment Models

A precise, codebase-verified guide to how BizFirst's .NET backends and React/Vite frontends are configured per environment — and exactly how the frontend finds its API, whether it's deployed inline with the server or as an independent app.

What This Site Covers

Two kinds of applications need to know "which environment am I running in, and where is my API" — a .NET server process and a React single-page app compiled by Vite. They answer that question in fundamentally different ways: one at runtime, one at build time. Misunderstanding that difference is the single most common source of "why is my frontend calling the wrong API" bugs. This site walks through the concept, then the concrete implementation in the Flow API and the FlowStudio React app.

This is a rewrite, not an update

An earlier version of this guide described a window.APP_CONFIG global and an automatic "NODE_ENV-based auto-tuning" mechanism for swapping API URLs at runtime. A full-repo search found no trace of either in the actual source. This site (V2) documents only what the code actually does, verified directly against bizfirst-common-js, flow-studio, and atlas-forms source files.

Three Chapters

Chapter 1 — Concepts

The mental model of "environments," how server processes and browser bundles each learn which environment they're in, and the two ways a React app can be deployed relative to its API.

6 pages

Chapter 2 — How It Works in BizFirst

Concrete .env samples, how Flow and FlowStudio are actually configured, and a deep dive into the calculateApiUrl() function fixed today.

4 pages

Chapter 3 — Guidelines

A step-by-step checklist for configuring a new deployment, plus a debugging playbook for the failure modes you'll actually hit.

2 pages

Where To Start

If you're a backend developer new to frontend deployment, start at the beginning of Chapter 1 — page 1.3 ("How .NET and React Read Environment Variables") explains the single biggest mental-model gap. If you already understand build-time vs runtime config and just need the concrete answer for "what happens when VITE_API_BASE_URL is empty," jump straight to 2.4 — Empty vs /api Path.