feat(deployment): Add new frontend system option (#98)

Add optional new-frontend-system (app-next) support on RHDHDeployment: merge
package NFS YAML with the same pipeline as common → auth → user (later wins),
instead of a separate loader path.
- Secrets: splice NFS secrets into mergeYamlFilesIfExists before a single
  envsubst pass (common → auth → NFS when active → user).
- Dynamic plugins: splice config/new-frontend-system/dynamic-plugins.yaml after
  auth and before workspace/generated config so NFS OCI entries act as defaults;
  user dynamic-plugins.yaml and metadata still override.
- Layout: move NFS assets to config/new-frontend-system/ (secrets.yaml,
  dynamic-plugins.yaml, value_file.yaml); group paths under
  DEFAULT_CONFIG_PATHS.newFrontendSystem (secrets, dynamicPlugins, valueFile).
- Drop duplicate includes from the NFS dynamic-plugins fragment (common already
  includes dynamic-plugins.default.yaml).
- Remove new-frontend-system-plugins.ts (env-based OCI overrides), its tests,
  and RHDH_E2E_NFS_*_ENV exports; pin app-auth / app-integrations via standard
  workspace dynamic-plugins.yaml.
- Auto-enable when configure() omits the flag if the namespace ends with
  -app-next or USE_NEW_FRONTEND_SYSTEM=true; explicit useNewFrontendSystem
  true/false still wins via ??.
Docs and tests updated for merge order, env var, and consumer migration notes.

Assisted-By: Cursor Desktop

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Author: gashcrumb

CLAUDE.md

@@ -25,7 +25,7 @@ src/
 │   │   ├── deployment.ts    # Main class (configure, deploy, waitUntilReady, teardown)
 │   │   ├── types.ts         # DeploymentOptions, DeploymentConfig
 │   │   ├── constants.ts     # Config paths, auth providers, chart URLs
-│   │   └── config/          # YAML templates (common/, auth/, helm/, operator/)
+│   │   └── config/          # YAML templates (common/, auth/, new-frontend-system/, helm/, operator/)
 │   ├── keycloak/            # KeycloakHelper — Keycloak Helm deployment + OIDC setup
 │   └── orchestrator/        # Workflow orchestrator installer
 ├── playwright/
@@ -81,18 +81,22 @@ yarn check     # typecheck + lint + prettier
 
 ## Key Architectural Concepts
 
-### Configuration Merging (3-level cascade)
+### Configuration Merging (layered cascade)
 
 ```
 Package defaults (config/common/)
   ↓ deep merge
 Auth-specific (config/auth/{keycloak|guest|github}/)
+  ↓ deep merge (when useNewFrontendSystem)
+New frontend system defaults (config/new-frontend-system/)
   ↓ deep merge
 User config (workspace's tests/config/*.yaml)
   ↓
 = Final merged config
 ```
 
+`useNewFrontendSystem` is true when set explicitly, when the namespace ends with `-app-next`, or when `USE_NEW_FRONTEND_SYSTEM=true`. Secrets use the same layer order, then a single `envsubst` pass on the merged result.
+
 Array merge uses "replace" strategy by default. Plugin arrays use `byKey: "package"` with normalized keys (strips trailing `-dynamic`).
 
 ### Plugin Metadata Resolution

docs/CLAUDE.md

@@ -200,7 +200,7 @@ When documenting, reference these source files:
 | YAML Merging | `src/utils/merge-yamls.ts` |
 | Bash ($) | `src/utils/bash.ts` |
 | envsubst | `src/utils/common.ts` |
-| Config Templates | `src/deployment/rhdh/config/{common,auth,helm,operator}/` |
+| Config Templates | `src/deployment/rhdh/config/{common,auth,new-frontend-system,helm,operator}/` |
 
 ## Common Tasks
 

docs/api/deployment/deployment-types.md

@@ -42,6 +42,8 @@ type DeploymentOptions = {
   method?: DeploymentMethod;
   valueFile?: string;
   subscription?: string;
+  disableWrappers?: string[];
+  useNewFrontendSystem?: boolean;
 };
 ```
 
@@ -56,6 +58,8 @@ type DeploymentOptions = {
 | `method` | `DeploymentMethod` | Installation method |
 | `valueFile` | `string` | Helm values file (Helm only) |
 | `subscription` | `string` | Backstage CR file (Operator only) |
+| `disableWrappers` | `string[]` | Wrapper plugins to disable (PR builds) |
+| `useNewFrontendSystem` | `boolean` | New frontend system (app-next / NFS). Omit to auto-detect from namespace suffix `-app-next` or `USE_NEW_FRONTEND_SYSTEM=true`; set `false` to disable. See [RHDH deployment](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) |
 
 ## DeploymentConfigBase
 
@@ -67,6 +71,8 @@ type DeploymentConfigBase = {
   appConfig: string;
   secrets: string;
   dynamicPlugins: string;
+  disableWrappers: string[];
+  useNewFrontendSystem: boolean;
 };
 ```
 

docs/changelog.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.41] - Current
+
+### Added
+
+- **`useNewFrontendSystem`** — Backstage **app-next** / new frontend system: merges NFS layers from `config/new-frontend-system/` (secrets, default **app-auth** and **app-integrations** plugins, Helm `value_file.yaml`) into the same merge pipelines as common/auth/user. Secrets are merged with other layers **before** a single `envsubst` pass. NFS dynamic plugins act as **defaults** (workspace `tests/config/dynamic-plugins.yaml` overrides). **Auto-detection:** enabled when the namespace ends with `-app-next` or `USE_NEW_FRONTEND_SYSTEM=true`, unless `useNewFrontendSystem: false` is passed. Optional workspace `tests/config/value_file-app-next.yaml` is still merged last for Helm.
+
 ## [1.1.40] - Current
 
 ### Changed

docs/guide/configuration/config-files.md

@@ -46,6 +46,10 @@ catalog:
 
 Configure dynamic plugins:
 
+::: tip `useNewFrontendSystem`
+If you run against the **app-next** shell, enable the new frontend system (pass `useNewFrontendSystem: true`, use a project/namespace suffix **`-app-next`**, or set **`USE_NEW_FRONTEND_SYSTEM=true`** — see [RHDH deployment](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem)). The package merges default **app-auth** and **app-integrations** OCI plugins as **defaults**; override versions in this file when they must differ.
+:::
+
 ```yaml
 includes:
   - dynamic-plugins.default.yaml

docs/guide/configuration/environment-variables.md

@@ -35,6 +35,7 @@ These are set automatically during deployment:
 | `CHART_URL`                           | Custom Helm chart URL                                         | `oci://quay.io/rhdh/chart` |
 | `SKIP_KEYCLOAK_DEPLOYMENT`            | Skip Keycloak auto-deploy                                     | `false`                    |
 | `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disable plugin metadata injection (local only, ignored in CI) | -                          |
+| `USE_NEW_FRONTEND_SYSTEM` | When `"true"`, enables new-frontend-system (app-next) merges when `useNewFrontendSystem` is not set in `configure()` options | - |
 
 ## Plugin Metadata Variables
 
@@ -53,6 +54,21 @@ These control automatic plugin configuration injection from metadata files.
 | `JOB_NAME`                            | CI job name (set by OpenShift CI/Prow)                  | If contains `periodic-`, nightly mode is activated                                                                                                                                       |
 | `JOB_MODE`                            | CI-only: `nightly` or `pr-check` (set by step registry) | Informational                                                                                                                                                                            |
 
+## New frontend system (app-next)
+
+NFS merge layers ship under `config/new-frontend-system/` in the package (secrets, dynamic plugins, Helm values), same layering idea as `auth/`.
+
+**Enabling app-next behavior**
+
+| Mechanism | Effect |
+|-----------|--------|
+| `useNewFrontendSystem: true` in [`configure()`](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) | Explicit enable |
+| `useNewFrontendSystem: false` | Explicit disable (overrides auto-detection) |
+| Playwright project / namespace ends with `-app-next` | Auto-enabled when `useNewFrontendSystem` is omitted |
+| `USE_NEW_FRONTEND_SYSTEM=true` | Auto-enabled for all namespaces when `useNewFrontendSystem` is omitted |
+
+**Overriding default OCI refs** for **app-auth** and **app-integrations** uses the same pattern as other plugins: add or adjust entries in your workspace `tests/config/dynamic-plugins.yaml` (merged after package NFS defaults, so your versions win).
+
 ### OCI URL Generation
 
 When `GIT_PR_NUMBER` is set, the package replaces local plugin paths with OCI URLs:

docs/guide/configuration/index.md

@@ -9,7 +9,7 @@ The package provides configuration tools for ESLint, TypeScript, and RHDH deploy
 | [Configuration Files](/guide/configuration/config-files) | YAML configuration structure |
 | [ESLint Configuration](/guide/configuration/eslint-config) | Pre-configured ESLint rules |
 | [TypeScript Configuration](/guide/configuration/typescript-config) | Base TypeScript settings |
-| [Environment Variables](/guide/configuration/environment-variables) | All environment variables |
+| [Environment Variables](/guide/configuration/environment-variables) | All environment variables (including NFS / app-next, e.g. `USE_NEW_FRONTEND_SYSTEM`) |
 | [Disabling Conflicting Wrappers](/guide/configuration/disable-wrappers) | Disabling pre-enabled wrappers that may cause configuration conflicts |
 
 ## Project Configuration
@@ -69,6 +69,8 @@ RHDH configurations are merged in layers:
 
 This allows you to override only what you need while using sensible defaults.
 
+For tests targeting the **new frontend system** (app-next), see [RHDH deployment — New frontend system](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) and [NFS-related options](/guide/configuration/environment-variables#new-frontend-system-app-next).
+
 ## Plugin Metadata Injection
 
 For PR builds, the package can automatically inject plugin configurations from metadata files. See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection) for details.

docs/guide/deployment/rhdh-deployment.md

@@ -57,6 +57,43 @@ test("example", async ({ rhdh }) => {
 | `dynamicPlugins` | `string` | Path to dynamic-plugins YAML |
 | `valueFile` | `string` | Helm values file (Helm only) |
 | `subscription` | `string` | Backstage CR file (Operator only) |
+| `disableWrappers` | `string[]` | Wrapper plugin package names to disable (`GIT_PR_NUMBER` flows) |
+| `useNewFrontendSystem` | `boolean` | Enables the Backstage **new frontend system** shell (app-next / NFS): merges app-next secrets, default OCI **app-auth** and **app-integrations** plugins (as defaults — override in `tests/config/dynamic-plugins.yaml`), and extra Helm values from `config/new-frontend-system/value_file.yaml` plus optional `tests/config/value_file-app-next.yaml`. Omit to **auto-detect**: on when the namespace ends with `-app-next` or `USE_NEW_FRONTEND_SYSTEM=true`. Pass `false` to force off. |
+
+### New frontend system (`useNewFrontendSystem`)
+
+Use the **app-next** frontend when any of these apply:
+
+- You pass `useNewFrontendSystem: true` in **`configure()`** (explicit), or
+- The Playwright project name (which becomes the Kubernetes namespace) ends with **`-app-next`**, or
+- You set environment variable **`USE_NEW_FRONTEND_SYSTEM=true`**
+
+Pass **`useNewFrontendSystem: false`** to run in a `-app-next` namespace without NFS layers.
+
+Typical explicit flow:
+
+```typescript
+await rhdh.configure({
+  auth: "keycloak",
+  useNewFrontendSystem: true,
+});
+await rhdh.deploy();
+```
+
+With a project named e.g. `my-plugin-app-next`, you can omit the flag and still get NFS merges:
+
+```typescript
+await rhdh.configure({ auth: "keycloak" });
+await rhdh.deploy();
+```
+
+What gets merged (same order as other config: package defaults → auth → NFS defaults → your workspace files; later wins; secrets are merged then **envsubst** runs once on the result):
+
+1. **Secrets** — `APP_CONFIG_app_packageName: app-next` and `ENABLE_STANDARD_MODULE_FEDERATION: "true"` (your `rhdh-secrets.yaml` still wins on conflicts and can use `$VAR` substitution).
+2. **Dynamic plugins** — Default OCI refs for `red-hat-developer-hub-backstage-plugin-app-auth` and `...-app-integrations` from package YAML; override pins in **`tests/config/dynamic-plugins.yaml`** (same as other plugins).
+3. **Helm** — Package `config/new-frontend-system/value_file.yaml`, then your `value_file.yaml`, then optional `tests/config/value_file-app-next.yaml` when that file exists.
+
+Workspace-specific **app-config** (titles, plugin routes, etc.) remains your responsibility.
 
 ### Example: Full Configuration
 
@@ -113,13 +150,14 @@ await rhdh.deploy({ timeout: null });
 `deploy()` automatically skips if the deployment already succeeded in the current test run (e.g., after a worker restart due to test failure). This prevents expensive re-deployments.
 
 This method:
-1. Merges configuration files (common → auth → project)
-2. [Injects plugin metadata](/guide/configuration/config-files#plugin-metadata-injection) into dynamic plugins config
-3. Applies ConfigMaps (app-config, dynamic-plugins)
-4. Applies Secrets (with environment variable substitution)
-5. Installs RHDH via Helm or Operator
-6. Waits for the deployment to be ready
-7. Sets `RHDH_BASE_URL` environment variable
+1. Merges configuration files (common → auth → optional NFS defaults → project overrides) for app-config, secrets, and dynamic plugins
+2. Substitutes environment variables in the merged secrets (`envsubst`)
+3. [Injects plugin metadata](/guide/configuration/config-files#plugin-metadata-injection) into dynamic plugins config
+4. Applies ConfigMaps (app-config, dynamic-plugins)
+5. Applies Secrets
+6. Installs RHDH via Helm or Operator
+7. Waits for the deployment to be ready
+8. Sets `RHDH_BASE_URL` environment variable
 
 #### Base URL format
 

docs/overlay/reference/environment-variables.md

@@ -42,6 +42,14 @@ See [Running Locally - Secrets from Vault](/overlay/tutorials/running-locally#se
 | `INSTALLATION_METHOD` | Deployment method: `helm` or `operator`      | `helm`                     | No       |
 | `CHART_URL`           | Custom Helm chart URL                        | `oci://quay.io/rhdh/chart` | No       |
 
+### New frontend system (app-next / NFS)
+
+When the new frontend system is active (see [`useNewFrontendSystem`](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) and [environment variables](/guide/configuration/environment-variables#new-frontend-system-app-next)), the package merges NFS defaults then your workspace files. Pin **app-auth** / **app-integrations** OCI refs in `tests/config/dynamic-plugins.yaml` like any other plugin (your file wins over package defaults).
+
+| Variable | Description |
+|----------|-------------|
+| `USE_NEW_FRONTEND_SYSTEM` | When `"true"`, enables NFS merges if `useNewFrontendSystem` is not set in `configure()` options |
+
 ### Cluster Configuration
 
 | Variable                  | Description                | Default       | Required |

docs/overlay/test-structure/configuration-files.md

@@ -27,11 +27,23 @@ tests/config/
 ├── rhdh-secrets.yaml       # Kubernetes secrets (optional)
 ├── dynamic-plugins.yaml    # Dynamic plugins (optional - usually not needed)
 ├── value_file.yaml         # Helm values override (optional, Helm only)
+├── value_file-app-next.yaml # Extra Helm values when new frontend system is active (optional)
 └── subscription.yaml       # Operator subscription (optional, Operator only)
 ```
 
 **All of these files are optional.** Only create them when you need to override or extend defaults.
 
+## `useNewFrontendSystem` (app-next / NFS)
+
+When the new frontend system is enabled (see [`configure()`](/guide/deployment/rhdh-deployment#configureoptions) and [New frontend system](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem)), `@red-hat-developer-hub/e2e-test-utils` merges:
+
+- **Secrets** — `APP_CONFIG_app_packageName=app-next` and `ENABLE_STANDARD_MODULE_FEDERATION=true` into the `rhdh-secrets` Secret (merged with common/auth/workspace layers before `envsubst`; you no longer need duplicate keys in a separate `rhdh-secrets-next.yaml` for that).
+- **Dynamic plugins** — Default OCI entries for **app-auth** and **app-integrations** as package defaults; override versions in `tests/config/dynamic-plugins.yaml` ([guide](/guide/configuration/config-files#dynamic-pluginsyaml)).
+
+You can **remove** hand-maintained `app-auth` / `app-integrations` lines from `dynamic-plugins.yaml` when the framework defaults match your train.
+
+Optional **`value_file-app-next.yaml`** is merged last when the new frontend system is active and the file exists — use for chart tweaks specific to app-next runs.
+
 ## app-config-rhdh.yaml (Optional)
 
 The main RHDH configuration file. This file is merged with default configurations from `@red-hat-developer-hub/e2e-test-utils`.