feat(deployment): Add new frontend system option

This change adds a useNewFrontendSystem option to configure the RHDH
deployment to load the new frontend system app-next package instead of
the old frontend system app package.  This change also adds the relevant
plugins in this mode that are required for logging in using other
authentication providers than the guest login as well as source control
authentication support.  Tests that want to use the new frontend system
simply need to set useNewFrontendSystem to "true" in the options object
for rhdh.configure().

Assisted-By: Cursor Desktop

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

Author: gashcrumb

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 shell); 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,7 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.1.37] - Current
+## [1.1.38] - Current
+
+### Added
+
+- **`useNewFrontendSystem`** — Optional flag on `rhdh.configure()` for Backstage **app-next** / new frontend system tests: merges `APP_CONFIG_app_packageName` and `ENABLE_STANDARD_MODULE_FEDERATION` into `rhdh-secrets`, adds default OCI dynamic plugins for **app-auth** and **app-integrations**, optional Helm merge layers (`value_file.new-frontend.yaml`, workspace `tests/config/value_file-app-next.yaml`). Env overrides: `RHDH_E2E_NFS_APP_AUTH_PACKAGE`, `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE` (full `oci://` refs). Exported constants `RHDH_E2E_NFS_APP_AUTH_PACKAGE_ENV` and `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE_ENV`. Types re-exported from `@red-hat-developer-hub/e2e-test-utils/rhdh`.
+
+## [1.1.37]
 
 ### Added
 

docs/guide/configuration/config-files.md

@@ -46,6 +46,10 @@ catalog:
 
 Configure dynamic plugins:
 
+::: tip `useNewFrontendSystem`
+If you run against the **app-next** shell, set `useNewFrontendSystem: true` on [`configure()`](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) so the package merges default **app-auth** and **app-integrations** OCI plugins (and optional [env overrides](/guide/configuration/environment-variables#new-frontend-system-app-next-shell-plugins)). You can then omit those entries from this file when the defaults match your train.
+:::
+
 ```yaml
 includes:
   - dynamic-plugins.default.yaml

docs/guide/configuration/environment-variables.md

@@ -48,6 +48,19 @@ These control automatic plugin configuration injection from metadata files:
 | `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, injection is disabled |
 | `JOB_MODE` | CI-only: `nightly` or `pr-check` (set by step registry) | Informational |
 
+## New frontend system (app-next shell plugins)
+
+When [`useNewFrontendSystem`](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) is `true`, the package adds default OCI packages for **app-auth** and **app-integrations**. You can override each with a **full** `oci://` reference (optional):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RHDH_E2E_NFS_APP_AUTH_PACKAGE` | Full `oci://` package ref for `red-hat-developer-hub-backstage-plugin-app-auth` | Baked default in package YAML |
+| `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE` | Full `oci://` package ref for `red-hat-developer-hub-backstage-plugin-app-integrations` | Baked default in package YAML |
+
+If an env var is **unset**, the default ref from the package is used. If set, it **replaces** that plugin entry (useful in CI to pin versions without publishing a new `@red-hat-developer-hub/e2e-test-utils` release).
+
+Constants matching these names are exported as `RHDH_E2E_NFS_APP_AUTH_PACKAGE_ENV` and `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE_ENV` from `@red-hat-developer-hub/e2e-test-utils/rhdh`.
+
 ### 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 shell plugin overrides) |
 | [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 [`useNewFrontendSystem`](/guide/deployment/rhdh-deployment#new-frontend-system-usenewfrontendsystem) on `configure()` and [NFS-related environment variables](/guide/configuration/environment-variables#new-frontend-system-app-next-shell-plugins).
+
 ## 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,30 @@ 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` | When `true`, enables the Backstage **new frontend system** shell (app-next): merges `APP_CONFIG_app_packageName` / `ENABLE_STANDARD_MODULE_FEDERATION` into `rhdh-secrets`, adds OCI **app-auth** and **app-integrations** dynamic plugins (with optional env overrides — see [Environment Variables](/guide/configuration/environment-variables#new-frontend-system-app-next-shell-plugins)), and merges extra Helm values (`value_file.new-frontend.yaml`, optional workspace `tests/config/value_file-app-next.yaml`). Defaults to `false`. |
+
+### New frontend system (`useNewFrontendSystem`)
+
+Set `useNewFrontendSystem: true` in **`configure()`** when tests must run against the **app-next** frontend (often called NFS in docs). Typical flow:
+
+```typescript
+await rhdh.configure({
+  auth: "keycloak",
+  useNewFrontendSystem: true,
+});
+await rhdh.deploy();
+```
+
+Do **not** rely on the worker fixture’s argument-free `configure()` call for this flag — pass it in `beforeAll` with the rest of your deployment options **before** `deploy()`, as you do for `auth` and custom config paths.
+
+What gets merged:
+
+1. **Secrets** — `APP_CONFIG_app_packageName: app-next` and `ENABLE_STANDARD_MODULE_FEDERATION: "true"` (workspace `rhdh-secrets.yaml` still supplies plugin-specific secrets).
+2. **Dynamic plugins** — Default OCI refs for `red-hat-developer-hub-backstage-plugin-app-auth` and `...-app-integrations`, overridable via `RHDH_E2E_NFS_APP_AUTH_PACKAGE` and `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE` (full `oci://` URIs).
+3. **Helm** — Package merge layer `config/helm/value_file.new-frontend.yaml` (shipped with the package), 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
 
@@ -114,12 +138,13 @@ await rhdh.deploy({ timeout: null });
 
 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
+2. Optionally applies **new frontend system** merges when [`useNewFrontendSystem`](#deploymentoptions) was set on `configure()` (secrets, optional OCI shell plugins, Helm layers)
+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 (with environment variable substitution)
+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,17 @@ 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 (optional OCI overrides)
+
+Used when tests call `configure({ useNewFrontendSystem: true })`. Same semantics as the [guide environment reference](/guide/configuration/environment-variables#new-frontend-system-app-next-shell-plugins): full `oci://` refs; unset keeps package defaults.
+
+| Variable | Description |
+|----------|-------------|
+| `RHDH_E2E_NFS_APP_AUTH_PACKAGE` | Override default OCI ref for app-auth |
+| `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE` | Override default OCI ref for app-integrations |
+
+Set these in Vault or CI job env when you need to pin shell plugin versions per pipeline.
+
 ### 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 useNewFrontendSystem is true (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 you pass `useNewFrontendSystem: true` to [`configure()`](/guide/deployment/rhdh-deployment#configureoptions), `@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 (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**, overridable via `RHDH_E2E_NFS_APP_AUTH_PACKAGE` / `RHDH_E2E_NFS_APP_INTEGRATIONS_PACKAGE` ([guide](/guide/configuration/environment-variables#new-frontend-system-app-next-shell-plugins)).
+
+You can **remove** hand-maintained `app-auth` / `app-integrations` lines from `dynamic-plugins.yaml` when the framework supplies them. Keep workspace-only plugins and metadata-driven config as today.
+
+Optional **`value_file-app-next.yaml`** is merged last when `useNewFrontendSystem` is true 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`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@red-hat-developer-hub/e2e-test-utils",
-  "version": "1.1.37",
+  "version": "1.1.38",
   "description": "Test utilities for RHDH E2E tests",
   "license": "Apache-2.0",
   "repository": {

src/deployment/rhdh/config/common/new-frontend-system-dynamic-plugins.yaml

@@ -0,0 +1,7 @@
+includes:
+  - dynamic-plugins.default.yaml
+plugins:
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-app-auth:bs_1.49.4__0.0.1
+    disabled: false
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-app-integrations:bs_1.49.4__0.0.1
+    disabled: false