From ab065f30c1422b8b4bba767e4c1c2f7f8fe983f7 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Sun, 12 Jul 2026 06:15:12 -0600 Subject: [PATCH 1/2] docs(env-vars): clarify loadEnv/.env cannot shape Harper's instance config loadEnv supplies application env vars (process.env), not Harper's own configuration. Config-shaping vars (HARPER_CONFIG/HARPER_SET_CONFIG/ HARPER_DEFAULT_CONFIG) delivered via .env are read after the instance config is composed and are ignored; Harper now logs a warning. Documents the warn-don't-honor behavior from harper#1513 / #1580. Co-Authored-By: Claude Opus 4.8 (1M context) --- reference/environment-variables/overview.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index d30d004b..b2893f7c 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -46,6 +46,14 @@ myApp: Because Harper is a single-process application, environment variables are loaded onto `process.env` and are shared across all components. As long as `loadEnv` is listed before dependent components, those components will have access to the loaded variables. +:::warning +`loadEnv` supplies **application** environment variables — values your component code reads from `process.env` (secrets, API endpoints, app settings). It does **not** configure Harper itself. + +Harper's own instance-wide configuration is composed once at startup, **before** any component's `loadEnv` runs. As a result, config-shaping variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late to take effect and are ignored (Harper logs a warning when it detects one). + +To change Harper's configuration, set it in the [configuration file](../configuration/overview.md) or export the variable in the real process/container environment **before** Harper starts — not through `loadEnv`. +::: + ## Override Behavior By default, `loadEnv` follows the standard dotenv convention: **existing environment variables take precedence** over values in `.env` files. This means variables already set in the shell or container environment will not be overwritten. From 8e0511e266a7899593f7dad2f6cee557581ae704 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Mon, 20 Jul 2026 11:38:04 -0600 Subject: [PATCH 2/2] =?UTF-8?q?docs(env-vars):=20address=20PR=20review=20?= =?UTF-8?q?=E2=80=94=20VersionBadge=20placement=20+=20grammar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move to its own line per CONTRIBUTING.md convention (keeping type="changed", confirmed correct per reviewer override of the bot suggestion), and fix "detects one" -> "detects any of them" for grammar. Co-Authored-By: Claude Sonnet 5 --- reference/environment-variables/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index b2893f7c..ed23c044 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -49,7 +49,9 @@ Because Harper is a single-process application, environment variables are loaded :::warning `loadEnv` supplies **application** environment variables — values your component code reads from `process.env` (secrets, API endpoints, app settings). It does **not** configure Harper itself. -Harper's own instance-wide configuration is composed once at startup, **before** any component's `loadEnv` runs. As a result, config-shaping variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late to take effect and are ignored (Harper logs a warning when it detects one). +Harper's own instance-wide configuration is composed once at startup, **before** any component's `loadEnv` runs. As a result, config-shaping variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late to take effect and are ignored (Harper logs a warning when it detects any of them). + + To change Harper's configuration, set it in the [configuration file](../configuration/overview.md) or export the variable in the real process/container environment **before** Harper starts — not through `loadEnv`. :::