From 28e35fb619c71461936e0ca4a86c415ee05f56d2 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 24 Feb 2026 14:01:04 -0700 Subject: [PATCH 1/4] docs: migrate Environment Variables section to v4 consolidated reference Adds the Environment Variables section focused on the built-in `loadEnv` plugin. Harper-level env var configuration (naming conventions, HDB_CONFIG, HARPER_DEFAULT_CONFIG, HARPER_SET_CONFIG) is intentionally deferred to the Configuration section, with research notes captured in the migration map. Co-Authored-By: Claude Sonnet 4.6 --- ...environment-variables-link-placeholders.md | 19 ++++ .../environment-variables/overview.md | 86 +++++++++++++++++++ .../version-v4-sidebars.json | 13 +++ v4-docs-migration-map.md | 17 ++-- 4 files changed, 129 insertions(+), 6 deletions(-) create mode 100644 migration-context/link-placeholders/environment-variables-link-placeholders.md create mode 100644 reference_versioned_docs/version-v4/environment-variables/overview.md diff --git a/migration-context/link-placeholders/environment-variables-link-placeholders.md b/migration-context/link-placeholders/environment-variables-link-placeholders.md new file mode 100644 index 00000000..8943b2ec --- /dev/null +++ b/migration-context/link-placeholders/environment-variables-link-placeholders.md @@ -0,0 +1,19 @@ +# Link Placeholders for Environment Variables + +## reference_versioned_docs/version-v4/environment-variables/overview.md + +- Line 14: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md)` + - Context: Intro list item — "Harper configuration via environment variables — see Configuration" + - Target should be: Configuration section overview page + +- Line 67: `[Resource Extension](TODO:reference_versioned_docs/version-v4/components/overview.md)` + - Context: Describing that `loadEnv` is a Resource Extension supporting standard `files`/`urlPath` config options + - Target should be: Components overview page (covering the Resource Extension concept) + +- Line 79: `[Components Overview](TODO:reference_versioned_docs/version-v4/components/overview.md)` + - Context: "Related" section + - Target should be: Main components/extensions reference page + +- Line 80: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md)` + - Context: "Related" section — linking to where env var config details live + - Target should be: Configuration section overview page diff --git a/reference_versioned_docs/version-v4/environment-variables/overview.md b/reference_versioned_docs/version-v4/environment-variables/overview.md new file mode 100644 index 00000000..8c25a530 --- /dev/null +++ b/reference_versioned_docs/version-v4/environment-variables/overview.md @@ -0,0 +1,86 @@ +--- +id: overview +title: Environment Variables +--- + + + + + +# Environment Variables + +Harper supports environment variables in two distinct ways: + +1. **Component-level `.env` files** — load environment variables from `.env` files into your components using the built-in `loadEnv` plugin. +2. **Harper configuration via environment variables** — configure Harper itself using environment variables and special bulk-config variables. See [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section overview, including environment variable configuration') for more information. + +## The `loadEnv` Built-In Plugin + +Added in: v4.5.0 (confirmed via release notes) + +Harper includes a built-in `loadEnv` plugin that loads environment variables from `.env` files into `process.env` before other components start. This is the standard way to supply secrets and configuration to your Harper components without hardcoding values. + +`loadEnv` does **not** need to be installed — it is built into Harper and only needs to be declared in your `config.yaml`. + +### Basic Usage + +```yaml +loadEnv: + files: '.env' +``` + +This loads the `.env` file from the root of your component directory into `process.env`. + +### Load Order + +> **Important:** Specify `loadEnv` first in your `config.yaml` so that environment variables are loaded before any other components start. + +```yaml +# config.yaml — loadEnv must come first +loadEnv: + files: '.env' + +rest: true + +myApp: + files: './src/*.js' +``` + +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. + +### 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. + +To override existing environment variables, use the `override` option: + +```yaml +loadEnv: + files: '.env' + override: true +``` + +### Multiple Files + +As a Harper plugin, `loadEnv` supports multiple files using either glob patterns or a list of files in the configuration: + +```yaml +loadEnv: + files: + - '.env' + - '.env.local' +``` + +or + +```yaml +loadEnd: + files: 'env-vars/*' +``` + +Files are loaded in the order specified. + +## Related + +- [Components Overview](TODO:reference_versioned_docs/version-v4/components/overview.md 'Components, Applications, and Extensions overview') +- [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section, including environment variable configuration conventions and HARPER_DEFAULT_CONFIG / HARPER_SET_CONFIG') diff --git a/reference_versioned_sidebars/version-v4-sidebars.json b/reference_versioned_sidebars/version-v4-sidebars.json index 7b60e0b1..f896b209 100644 --- a/reference_versioned_sidebars/version-v4-sidebars.json +++ b/reference_versioned_sidebars/version-v4-sidebars.json @@ -33,6 +33,19 @@ } ] }, + { + "type": "category", + "label": "Environment Variables", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "environment-variables/overview", + "label": "Overview" + } + ] + }, { "type": "category", "label": "GraphQL Querying", diff --git a/v4-docs-migration-map.md b/v4-docs-migration-map.md index 5a117cc6..9c55190d 100644 --- a/v4-docs-migration-map.md +++ b/v4-docs-migration-map.md @@ -65,10 +65,19 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - Current `reference/configuration.md` - `versioned_docs/version-4.1/configuration.md` (baseline) - **Status**: Not Started +- **Notes**: Must include a dedicated section on environment variable configuration. Content researched and ready from the environment-variables migration: + - **Naming convention**: YAML keys map to `SCREAMING_SNAKE_CASE` env vars (e.g. `http.port` → `HTTP_PORT`, `operationsApi.network.port` → `OPERATIONSAPI_NETWORK_PORT`). Case-insensitive. Component configuration cannot be set this way. + - **`HDB_CONFIG`**: CLI/ENV variable to specify a custom config file path at install time. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 51-55. + - **`HARPER_DEFAULT_CONFIG`**: Added in v4.7.2. Sets default config values as JSON, respects user edits, restores original on key removal. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 80-116 + `release_notes/4.7.2.md`. + - **`HARPER_SET_CONFIG`**: Added in v4.7.2. Forces config values that always win, even over user edits. Deleted (not restored) on key removal. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 118-145 + `release_notes/4.7.2.md`. + - **Configuration precedence**: `HARPER_SET_CONFIG` > user manual edits > `HARPER_DEFAULT_CONFIG` > file defaults. + - **State tracking**: Harper maintains `{rootPath}/backup/.harper-config-state.json` for drift detection and restoration. + - Full content is in `reference_versioned_docs/version-v4/environment-variables/configuration.md` — this file should be deleted after porting its content here. - **Release Notes**: - [4.2.0](release-notes/v4-tucker/4.2.0.md) - Major config changes (http section, componentRoot) - [4.3.0](release-notes/v4-tucker/4.3.0.md) - Configuration improvements - [4.4.0](release-notes/v4-tucker/4.4.0.md) - Developer/production mode + - [4.7.2](release-notes/v4-tucker/4.7.2.md) - HARPER_SET_CONFIG and HARPER_DEFAULT_CONFIG added ### `reference/configuration/options.md` @@ -402,15 +411,11 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: New content about `loadEnv` plugin - **Additional Sources**: Built-in extensions docs, configuration docs - **Version Annotations**: loadEnv added in v4.5.0 -- **Status**: Not Started +- **Status**: In Progress +- **Notes**: Covers `loadEnv` extension only. Harper-level environment variable configuration (naming conventions, `HDB_CONFIG`, `HARPER_DEFAULT_CONFIG`, `HARPER_SET_CONFIG`) belongs in the Configuration section — see notes there. - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Built-in loadEnv component -### `reference/environment-variables/configuration.md` - -- **Primary Source**: Extract from configuration docs or components docs -- **Status**: Not Started - --- ## Static Files Section From 9a4b725029b159fd6e67355af3748c2e01af3c50 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 24 Feb 2026 14:34:24 -0700 Subject: [PATCH 2/4] Update overview.md Co-authored-by: Chris Barber --- .../version-v4/environment-variables/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference_versioned_docs/version-v4/environment-variables/overview.md b/reference_versioned_docs/version-v4/environment-variables/overview.md index 8c25a530..acea3150 100644 --- a/reference_versioned_docs/version-v4/environment-variables/overview.md +++ b/reference_versioned_docs/version-v4/environment-variables/overview.md @@ -74,7 +74,7 @@ loadEnv: or ```yaml -loadEnd: +loadEnv: files: 'env-vars/*' ``` From 810025bff60f88f635229835e64fc53c4f7efd50 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 24 Feb 2026 14:57:55 -0700 Subject: [PATCH 3/4] adjust intro --- .../version-v4/environment-variables/overview.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/reference_versioned_docs/version-v4/environment-variables/overview.md b/reference_versioned_docs/version-v4/environment-variables/overview.md index acea3150..230f8352 100644 --- a/reference_versioned_docs/version-v4/environment-variables/overview.md +++ b/reference_versioned_docs/version-v4/environment-variables/overview.md @@ -9,18 +9,11 @@ title: Environment Variables # Environment Variables -Harper supports environment variables in two distinct ways: +Harper supports loading environment variables in Harper applications `process.env` using the built-in `loadEnv` plugin. This is the standard way to supply secrets and configuration to your Harper components without hardcoding values. `loadEnv` does **not** need to be installed as it is built into Harper and only needs to be declared in your `config.yaml`. -1. **Component-level `.env` files** — load environment variables from `.env` files into your components using the built-in `loadEnv` plugin. -2. **Harper configuration via environment variables** — configure Harper itself using environment variables and special bulk-config variables. See [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section overview, including environment variable configuration') for more information. - -## The `loadEnv` Built-In Plugin - -Added in: v4.5.0 (confirmed via release notes) - -Harper includes a built-in `loadEnv` plugin that loads environment variables from `.env` files into `process.env` before other components start. This is the standard way to supply secrets and configuration to your Harper components without hardcoding values. - -`loadEnv` does **not** need to be installed — it is built into Harper and only needs to be declared in your `config.yaml`. +:::note +If you are looking for information on how to configure your Harper installation using environment variables, see [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section overview, including environment variable configuration') section for more information. +::: ### Basic Usage From 72bd396b63ea9c535959224646fa207e3897b169 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 24 Feb 2026 14:58:56 -0700 Subject: [PATCH 4/4] fix titles --- .../version-v4/environment-variables/overview.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/reference_versioned_docs/version-v4/environment-variables/overview.md b/reference_versioned_docs/version-v4/environment-variables/overview.md index 230f8352..2b66a486 100644 --- a/reference_versioned_docs/version-v4/environment-variables/overview.md +++ b/reference_versioned_docs/version-v4/environment-variables/overview.md @@ -7,15 +7,13 @@ title: Environment Variables -# Environment Variables - Harper supports loading environment variables in Harper applications `process.env` using the built-in `loadEnv` plugin. This is the standard way to supply secrets and configuration to your Harper components without hardcoding values. `loadEnv` does **not** need to be installed as it is built into Harper and only needs to be declared in your `config.yaml`. :::note If you are looking for information on how to configure your Harper installation using environment variables, see [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section overview, including environment variable configuration') section for more information. ::: -### Basic Usage +## Basic Usage ```yaml loadEnv: @@ -24,7 +22,7 @@ loadEnv: This loads the `.env` file from the root of your component directory into `process.env`. -### Load Order +## Load Order > **Important:** Specify `loadEnv` first in your `config.yaml` so that environment variables are loaded before any other components start. @@ -41,7 +39,7 @@ 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. -### Override Behavior +## 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. @@ -53,7 +51,7 @@ loadEnv: override: true ``` -### Multiple Files +## Multiple Files As a Harper plugin, `loadEnv` supports multiple files using either glob patterns or a list of files in the configuration: