From 067593e223dab04de0d3f4a3abace9677e3e21ea Mon Sep 17 00:00:00 2001 From: Kyle Bernhardy Date: Thu, 2 Jul 2026 14:02:46 -0600 Subject: [PATCH 1/2] Document config-shaping env vars via loadEnv (harper#1580) Companion to HarperFast/harper#1580 (fixes HarperFast/harper#1513): HARPER_CONFIG / HARPER_SET_CONFIG / HARPER_DEFAULT_CONFIG delivered via a component .env are now applied before config composition. Documents precedence, encrypted-value and componentsRoot limitations. Co-Authored-By: Claude Fable 5 --- reference/environment-variables/overview.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index d30d004b..75011a09 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -78,6 +78,19 @@ loadEnv: Files are loaded in the order specified. +## Config-Shaping Variables + + + +The three configuration env vars — `HARPER_DEFAULT_CONFIG`, `HARPER_CONFIG`, and `HARPER_SET_CONFIG` (see [Configuration](../configuration/overview.md)) — shape Harper's root configuration, which is composed once at startup, before components load. When one of these is delivered through a `loadEnv` `.env` file, Harper applies it before composing the configuration, so `.env` delivery behaves the same as setting a real process environment variable. (Prior to 5.2.0, these variables silently had no effect when delivered via `.env`, because they were read after the configuration had already been composed.) + +Notes and limitations: + +- A real process environment variable still takes precedence over the `.env` value, unless the component declares `override: true`. +- Encrypted (`enc:v1:`) values cannot shape configuration — secret decryptors are not registered until components load. Such values are skipped with an error log. +- `componentsRoot` cannot be redirected this way: Harper discovers the `.env` files by scanning the components root from the config file, so a `componentsRoot` override delivered via env var or `.env` cannot change where that scan looks. +- Only these three variables are applied early. All other `.env` keys load at component-load time as usual. + ## Related - [Components Overview](../components/overview.md) From 938746d299c99d488e23b17f6e74511ecb9507b4 Mon Sep 17 00:00:00 2001 From: Kyle Bernhardy Date: Thu, 2 Jul 2026 14:05:22 -0600 Subject: [PATCH 2/2] Clarify override belongs to the loadEnv config block Co-Authored-By: Claude Fable 5 --- reference/environment-variables/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index 75011a09..55fca4a7 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -86,7 +86,7 @@ The three configuration env vars — `HARPER_DEFAULT_CONFIG`, `HARPER_CONFIG`, a Notes and limitations: -- A real process environment variable still takes precedence over the `.env` value, unless the component declares `override: true`. +- A real process environment variable still takes precedence over the `.env` value, unless `loadEnv` is configured with `override: true`. - Encrypted (`enc:v1:`) values cannot shape configuration — secret decryptors are not registered until components load. Such values are skipped with an error log. - `componentsRoot` cannot be redirected this way: Harper discovers the `.env` files by scanning the components root from the config file, so a `componentsRoot` override delivered via env var or `.env` cannot change where that scan looks. - Only these three variables are applied early. All other `.env` keys load at component-load time as usual.