Skip to content

Portal SDK npm package readiness

This document proposes the npm publication scope for third-party developers building Portal plugins in their own repositories. It inventories the packages and records local packaging checks. It does not announce a release, promise a supported platform matrix, or authorize publishing.

The inventory uses repository baseline a3ee4523 plus the packaging changes in this branch, with Backstage 1.54.9, Backstage CLI 0.36.5, Yarn 4.12.0, and RHDH CLI 1.10.8 for the original checks. Native export tooling on this branch now uses RHDH CLI 2.1.2.

Preview metadata preparation

The ten candidates below are prepared together as 0.1.0-alpha.0, with the private: true guard removed and public access metadata. The intended distribution tag is next. This makes the reviewed candidates publishable, but does not publish them or authorize a release. Feature packages retain their existing metadata. Yarn removes private: false when persisting manifests, so the candidates omit the field. Release checks accept both public forms and reject private packages.

The original packaging results below describe the earlier 0.1.0 private candidates. Repeat validation for this preview revision. The release workflow requires completed CodeQL analyses for the exact merged commit and selected release branch, a clean dependency audit, archive validation and SBOMs before an approved publication. Local checks cannot substitute another commit's evidence.

First publication remains subject to an agreed bootstrap procedure with the @ansible namespace owners and security maintainers. All ten names returned HTTP 404 from the public registry on 2026-11-19. An authorized owner must also check whether any name already exists privately. See the publishing prerequisites and bootstrap procedure.

Preview validation results (2026-11-19)

On Node 22.22.3, the prepared preview passes declaration emission, all ten package builds, archive metadata/content checks and an isolated consumer install. The consumer passes TypeScript, frontend bundling and backend health/runtime checks. All ten archives have verified SPDX 2.3 SBOMs generated with Syft 1.57.1. The 63 validation-tooling tests and immutable repository installation also pass. The full repository suite passes with 457 suites and 6,917 tests, with one suite and five tests skipped.

Requiring @backstage/catalog-model@1.10.2 in the affected candidate dependencies and peer ranges moves that dependency path from Zod 3 to Zod 4. The repository lockfile also selects patched Zod 4.6.7 for compatible Zod 4 ranges. Existing consumers that require Zod 3 are not forced across a major version. This change therefore does not eliminate every affected Zod dependency from the repository.

Earlier local audit counts are omitted because their source commit was replaced by rebasing and their output is not retained as reproducible release evidence. They do not establish the current dependency graph or security status. The SCM dependencies merged in #1054 also require a fresh consumer audit.

To reproduce candidate validation and dependency scanning from a reviewed revision, use a fresh checkout and inspect untracked files before running:

git status --porcelain --untracked-files=all

The report's includesUncommittedChanges flag detects tracked changes only. It does not detect untracked inputs, including extra .d.ts files copied from the consumer fixture. Remove untracked validation inputs before the run or commit and review them. Do not associate results with a revision based on this flag alone. Retain the output directory and run the following subshell. It stops if validation or changing directory fails without closing an interactive shell:

(
set -e
SDK_VALIDATION_DIR=/absolute/path/to/fresh-sdk-validation yarn validate:sdk-packages
cd /absolute/path/to/fresh-sdk-validation/consumer
if yarn npm audit --recursive --environment production --severity info --no-deprecations --json > yarn-audit.ndjson 2> yarn-audit.stderr.log; then
  audit_status=0
else
  audit_status=$?
fi
printf '%s\n' "$audit_status" > yarn-audit.exit-code
test "$audit_status" -eq 0
)

Retain yarn-audit.ndjson, yarn-audit.stderr.log, yarn-audit.exit-code, the consumer's yarn.lock and the validation report.json together. A clean audit can produce empty stdout; empty output alone does not establish success. The recorded exit status and stderr distinguish that result from a failed command. Findings or a failed scan keep the final check nonzero. Check the source SHA, tracked-change flag and untracked-input inventory before associating results with a revision. Packed-candidate validation, dependency auditing and exact-commit CodeQL checks are distinct checks; successful PR package validation alone is not a clean security report. The publishing workflow requires security evidence for its exact release revision and branch.

These changes retain the Backstage 1.54.9 and RHDH 2.1 baseline. Hosts consuming the revised peer ranges must satisfy the catalog-model ^1.10.2 minimum. An unchanged RHDH image is not proven to satisfy that minimum by local source or packed-consumer checks. Live validation of the changed package set remains a separate requirement.

Remaining dependency paths require compatible upstream fixes or backports:

  • The RHDH global-header package pulls in search backend and TechDocs dependencies that lead to the GraphQL Tools, basic-ftp and file-type findings. The published 3.3.1 manifest still declares those dependency paths.
  • Backstage integration dependencies lead to the three Octokit advisories.
  • Backstage core components lead to the PrismJS finding through refractor, and some UUID findings through material-table. Published react-syntax-highlighter 15.6.6 still depends on refractor 3.6.0, which requires PrismJS ~1.27.0.
  • The React Router 6 line remains affected by two advisories whose published patched versions start at 7.18.0. Do not force Router 7 into a Router 6 host.
  • UUID also has affected paths through the global-header backend dependencies.

These findings still block publication under the existing all-findings policy. No advisory exclusions, blanket cross-major resolutions or security-policy exceptions are introduced. Recheck the exact merged release revision after upstream remediation. See the Zod advisory and React Router advisory.

The latest main CodeQL analyses for 5b34e298350a0a67a5cc6cdaf4097dbf2a7d9ed9 report zero findings within the boundary computed from these archives. This is baseline evidence only. The preview metadata changes are not included in that commit, and the release workflow must obtain analyses for the final merged revision and selected release branch.

Publication scope

Publish the SDK libraries and supporting packages needed to author and host external contributors. Feature plugins from the AAP, APME, content management, and content development workspaces are outside this publication proposal.

Authors install only the libraries their contributor imports. Host packages are installed by the application maintainer. The SDK does not require every author to install a host, an authentication backend, or the existing feature plugins.

SDK and host libraries

All five use the coordinated 0.1.0-alpha.0 preview metadata described above.

  • @ansible/portal-extension-common — shared manifest, contribution, operation, and content-type contracts. No internal runtime package dependencies.
  • @ansible/portal-extension-api — frontend contribution APIs, native blueprints, API references, and registration helpers. Depends on portal-extension-common. Native entry point: /alpha.
  • @ansible/portal-plugin-sdk — reusable React components, hooks, styling, notifications, and presentation utilities. No internal runtime package dependencies. Optional for contributors that do not use its UI helpers.
  • @ansible/portal-plugin-node — backend plugin helpers, identity context, operations, entitlements, audit, and health services. Requires portal-extension-common as a peer dependency. Optional for frontend-only contributors.
  • @ansible/portal-extension-host — host rendering, validation, contribution composition, and discovery. Depends on portal-extension-api. Native entry point: /alpha. This is a host-maintainer dependency, not a normal contributor-author dependency. It is grouped with libraries for packaging, but should not be presented as an author prerequisite.

Host and runtime plugins

All four use the coordinated 0.1.0-alpha.0 preview metadata. Each is a supporting package, not a dependency every contributor must declare.

  • @ansible/portal-core — native frontend host and navigation. Depends on portal-extension-api and portal-extension-host. Exposes /alpha and /app-nav in addition to its root entry point.
  • @ansible/portal-rhdh — RHDH global-header adapter. Depends on portal-extension-host and portal-plugin-sdk. Exposes /alpha. Its RHDH header dependency remains outside the generic author SDK.
  • @ansible/portal-operations-backend — backend operation dispatch. Depends on portal-extension-common and portal-plugin-node. Exposes /alpha. Install when the host needs the Portal operation API.
  • @ansible/portal-health-backend — backend health aggregation. Depends on portal-plugin-node, whose common-contract peer must also be available. Install when the host needs the Portal health API.

Optional frontend authentication package

@ansible/aap-app-auth uses the same 0.1.0-alpha.0 preview metadata. It exports rhAapAuthApiRef for consumers needing the user's AAP credentials, and /alpha supplies the native sign-in and profile contribution module. It depends on portal-extension-api for the profile contribution.

A consumer importing the auth API reference does not need to directly depend on the other SDK packages or feature plugins. Its package manager still resolves the auth package's declared transitive dependencies. The host must provide the configured frontend AAP auth API, the @ansible/backstage-plugin-auth-backend-module-rhaap-provider backend module, and auth.providers.rhaap configuration. Publishing or installing the frontend package alone does not supply these host prerequisites.

The /api-module entry registers the native AAP API without adding sign-in or profile UI. Hosts may opt into /sign-in and the /profile factory separately. The combined /alpha entry keeps its existing API/sign-in/profile declarations and remains automatically discovered for compatibility. It adds the AAP provider row automatically when native user-settings is installed. Existing dynamic hosts can disable its AAP sign-in/profile extensions to retain standard RHDH UI. Do not install combined and separate modules together. The /settings factory preserves standard provider rows and adds AAP connection controls. Dynamic hosts receive this through /alpha without a Settings enablement flag. The user-settings plugin is an optional peer, required only when using that integration. Settings disconnects the AAP credential session without triggering full host or OIDC browser logout.

See workspaces/aap/plugins/aap-app-auth/README.md for exact composition, configuration and backend prerequisites. Validate actual standard RHDH coexistence and Portal login/logout before release; package tests and packing alone do not establish live host compatibility.

The API/UI separation was checked against upstream baseline 1ee4427d: auth package tests, repository TypeScript, package build, clean dynamic export and packed subpath checks passed. The new auth tarball also installed, compiled and bundled in the separate consumer project. The combined /alpha entry supplies Settings by default, and the frontend framework ignores the unattached Settings extension when user-settings is absent. Live RHDH validation exposed a limitation in RHDH CLI 1.10.8: additional feature loader metadata did not produce a federated loader export. Settings therefore uses the existing /alpha entry instead. Inspecting package metadata alone does not verify that the host can load every declared feature. The older ten-package consumer results below remain tied to their recorded baseline and must be repeated for release.

The optional Settings integration adds coverage for default-on loading and absent-host handling, preserved standard/custom rows, missing AAP API, account display, provider sign-in, disconnection and error reporting. The auth suite now has 44 passing tests, and source-app composition tests pass. The AAP row was verified in the live source Settings page alongside GitHub and GitLab without disconnecting those sessions. Updated packed Settings entry points compile and bundle in the separate consumer, and the clean dynamic export passes.

Local RHDH 2.1.0 validation on Backstage 1.54.9 used the automation-portal-local Compose harness and freshly exported dynamic artifacts. The AAP Settings row appeared automatically alongside the standard RHDH shell. Manual testing confirmed AAP login and, after enabling the Portal profile integration, full profile-menu Sign out. Settings Sign out remains a provider credential disconnect and intentionally leaves the AAP browser SSO session active. This instance used AAP as its host identity. Preserving an authenticated non-AAP host session during that disconnect needs a separate live check before claiming support for that configuration.

The tested AAP authorization endpoint returned Cross-Origin-Opener-Policy: same-origin, and popup login reported a closed window after the callback completed. The validation host used Backstage's enableExperimentalRedirectFlow: true configuration to complete login through same-tab redirects without changing AAP's security headers. These results cover this local configuration, not a supported compatibility matrix.

The backend provider is an existing host prerequisite, not part of the initial ten-package packing candidate set. If publishing that backend becomes necessary, its current internal runtime dependency chain is:

  • @ansible/backstage-plugin-auth-backend-module-rhaap-provider (2.3.1) depends on @ansible/backstage-rhaap-common (2.3.1) and @ansible/aap-common (0.1.0).
  • @ansible/backstage-rhaap-common also depends on @ansible/aap-common.
  • All three currently have private: true. Their existing versions must not be reset or aligned with SDK preview versions without reviewing release history.
  • Automatic catalog-user provisioning additionally needs the host's provisioning module and catalog configuration. It is not implied by installing an npm auth library.

Internal dependency map

Arrows mean a package declares a runtime dependency, except the labeled peer. This is an npm dependency map, not frontend activation or backend startup order. External Backstage, React, Express, and RHDH dependencies are omitted.

graph TD
    api[portal-extension-api] --> common[portal-extension-common]
    node[portal-plugin-node] -->|peer| common
    host[portal-extension-host] --> api
    core[portal-core] --> api
    core --> host
    rhdh[portal-rhdh] --> host
    rhdh --> sdk[portal-plugin-sdk]
    operations[portal-operations-backend] --> common
    operations --> node
    health[portal-health-backend] --> node
    auth[aap-app-auth] --> api

The internal dependency closure for these ten candidates contains no feature plugin packages. Publish or otherwise make dependencies available before their dependents, including the common-contract peer required by the backend SDK.

For a frontend contribution, the smallest internal dependency chain is portal-extension-api and portal-extension-common. Add portal-plugin-sdk only for its UI helpers. A backend author using portal-plugin-node must also provide its portal-extension-common peer. Host composition packages are separate from those author dependencies.

The generic contribution SDK remains usable without AAP authentication. Scaffolder field libraries in content development are not included in the first scope. Include those reusable libraries only if an external author's agreed use case requires them. This does not add the Portal scaffolder feature plugin to npm scope.

Historical packaging findings

These results describe the original private 0.1.0 candidates. They are retained as baseline evidence and do not establish readiness of the new preview revision.

Local checks use freshly emitted TypeScript declarations, package builds, and yarn workspace <package> pack --out <temporary-path>. These commands create local tarballs only. They do not publish to npm or a container registry.

Confirmed SDK library checks

The five libraries above build and pack locally. Their packed manifests resolve root entry points, declared export subpaths, and declaration paths to files present in the archive. Internal runtime and peer dependency ranges become ^0.1.0 rather than retaining workspace: references.

Source manifests pointing to src/ are not by themselves a publication defect. The installed Backstage prepack hook rewrites entry points to built artifacts, and postpack restores the source manifests. Inspect the generated archive instead of rewriting source exports solely because they point to TypeScript.

All ten baseline archives retained private: true, preventing publication, and kept their existing 0.1.0 versions. Each contains a LICENSE file identical to the repository Apache-2.0 license. The earlier missing-license finding is resolved for the candidate packages. This checks the repository license text, not third-party dependency licenses, required third-party notices, or security approval.

Supporting plugin checks

All five supporting plugins now build and pack with the required metadata:

  • portal-core, portal-rhdh, portal-operations-backend, and portal-health-backend each declare backstage.pluginPackages with their own package name. No other package in this repository declares the same respective plugin ID.
  • aap-app-auth declares backstage.pluginPackage: '@backstage/plugin-app', matching the native app plugin it extends. The module's misleading plural pluginPackages entry is removed.

All ten tarballs passed checks that declared main, module, types, export, and configuration-schema targets exist. Runtime and peer dependencies contain no workspace:, file:, link:, or portal: references. Each baseline tarball included its license and retained the private guard. Archive file lists contain no .env, .git, node_modules, or app-config*.yaml files. These filename checks are not a secret-content scan or a substitute for security review.

All ten candidate builds and the root TypeScript declaration emission passed on Node 22.22.3. The separate packed-consumer checks below also passed. Dynamic exports, dependency vulnerability scanning and dependency-license review are separate release checks.

Separate packed-consumer checks

A fresh consumer project outside this monorepo installed all ten candidate archives on 2026-11-06, using Yarn 4.12.0 and the Node 22.22.3 runtime. It had its own manifest and lockfile, with no workspace links or inherited root lockfile. Internal @ansible dependencies were resolved to the candidate tarballs through explicit consumer resolutions because these candidates are not yet published. The declared external peers were installed explicitly. The consumer pinned the reference host's @backstage/core-app-api@1.20.4 context and used RJSF 5.24.13 peers to satisfy the host package's declared ranges.

The following checks passed:

  • TypeScript compilation of a native frontend contributor using the public profile-item blueprint and generic SDK UI components, plus a backend contributor using the backend SDK and health service reference.
  • Compilation of host/auth root and subpath imports, including native entry points and the Portal navigation entry point.
  • Browser bundles of the frontend contributor and host/auth imports, resolving their dependency graphs from installed archives.
  • Runtime import of the backend host features and an SDK health push/read check.
  • All ten internal package paths resolve inside the isolated consumer's node_modules. Browser bundle inputs contain no monorepo source paths.

These checks validate installation, selected public API use, bundling and a bounded backend runtime path. They do not validate live host discovery, API identity across independently bundled dynamic plugins, permissions, operation execution, AAP login/logout, or RHDH installation. Consumer TypeScript compilation used skipLibCheck: true, so it is not a full third-party declaration audit.

Lifecycle scripts were disabled during the consumer install. Packages requiring native build scripts were not exercised. The install completed with Material UI 4 peer-range warnings against React 18 and its types. Record and review these warnings when choosing the release compatibility matrix; a successful install does not resolve that compatibility question.

RHDH CLI export tooling

The root RHDH CLI is pinned to 2.1.2, with its required ts-morph peer declared explicitly. CLI 2.1 uses native module federation and NFS feature metadata for frontend exports. Native scripts no longer pass the removed Scalprum generation flags, and native frontend package file lists no longer advertise dist-scalprum. Use export-dynamic --clean when switching export toolchains to remove stale outputs.

The content-management frontend still requires its owners' NFS migration. Its three CLI-owning workspaces retain an explicit 1.10.8 pin and use their local CLI binary instead of the root binary. This preserves the legacy content export path without adding feature plugins to the SDK publication scope. Remove this exception after the content owners migrate and validate their frontend.

Local checks with CLI 2.1.2 passed for six native frontend exports, the operations/health/AAP-auth backend exports, and a Node 24 AAP-auth export. Generated frontend feature declarations matched the federation exposes. The content frontend also exported successfully with its local CLI 1.10.8, retaining the legacy Scalprum manifest. The root lockfile installs immutably. Existing heavy-dependency warnings for core-app-api remain in AAP auth and Portal scaffolder; these exports did not enable --strict-deps.

The earlier live RHDH login/logout checks used artifacts exported before this CLI upgrade. Repeat live host validation with the selected release artifacts.

Reproducing the candidate packing checks

For the automated build, archive audit, and isolated-consumer check, run:

yarn validate:sdk-packages

The command uses the explicit candidate list in scripts/sdk-package-validation/packages.json and writes evidence outside the checkout. The SDK package validation workflow runs it on Node 22 and 24 for relevant pull requests. It does not publish packages or establish production readiness. See scripts/sdk-package-validation/README.md for checks, output, and limitations. The complete automated command passed locally on 2026-11-10 with Node 22.22.3 and 24.16.0 for all ten candidates. These runs include the auth composition and Settings federation fixes on this branch. Existing Material UI peer warnings remain documented limitations. The commands below are useful for inspecting individual archives.

Prerequisites

  • Install repository dependencies with the configured Yarn version.
  • Use Node 22 or 24, as declared by the repository.
  • Run the commands from the repository root.

Procedure

  1. Emit declarations using the current checkout:
yarn tsc
  1. Build and pack all ten candidates into a temporary directory:
set -e
package_artifacts="$(mktemp -d)"
for package in portal-extension-common portal-extension-api portal-plugin-sdk portal-plugin-node portal-extension-host portal-core portal-rhdh portal-operations-backend portal-health-backend aap-app-auth; do
  yarn workspace "@ansible/$package" build
  yarn workspace "@ansible/$package" pack --out "$package_artifacts/$package.tgz"
done

Verification

Confirm that each command exits successfully. Inspect an archive's published metadata and file list, including any subpath declaration files:

tar -xOf "$package_artifacts/portal-extension-api.tgz" package/package.json
tar -tzf "$package_artifacts/portal-extension-api.tgz"

Resolve every main, module, types, and export target against the archive contents. Check internal runtime and peer dependency ranges, license files, notices, and unintended files. Repeat for each archive. A successful local pack does not authorize publication or validate a real host install.

Release decisions and acceptance gates

  1. Approve the package allowlist. Start with the five libraries, distinguish host-only consumers, and confirm which supporting plugins need npm delivery for the first external integration. Keep feature plugins excluded. Freeze the intended public API before cutting artifacts. The branch includes the merged experience-ID removal, but the historical ten-package consumer results predate it. Repeat packing and consumer checks on the selected merged release revision rather than releasing those baseline artifacts unchanged.
  2. Review versions and tags. The candidates use 0.1.0-alpha.0 with the intended next tag. Yarn rewrites internal workspace references to matching preview ranges during packing. Dynamic OCI artifacts remain outside this release. If an approved bootstrap publishes this version, prepare a new coordinated version before running the automated publisher.
  3. Finalize publishable metadata and contents. The initial metadata and repository-license gaps are fixed and tarballs pass local checks. Only the ten candidates have their private guards removed. Review required plugin metadata, licenses and notices. Validate root and subpath imports and configuration schemas from the packed files.
  4. Validate host authentication composition. API-only and opt-in UI entry points are implemented, with the combined entry retained for compatibility. Verify the documented backend prerequisites and test standard RHDH coexistence and Portal login/logout using the release artifacts. A successful package test or pack does not establish live OAuth behavior.
  5. Complete separate-consumer runtime validation. Packed installation, selected frontend/backend compilation, browser bundling and a backend SDK runtime smoke check have passed outside the monorepo. Next verify live host discovery, shared API identity, permissions, operations and required AAP authentication using the selected release artifacts. The bounded checks above do not prove those host behaviors.
  6. Agree compatibility. Backstage 1.54.9 is the source baseline. Previous local RHDH testing against next-2.1 is not a supported-version declaration. Record an immutable RHDH image digest and test the actual release candidates. Validate peers rather than widening their ranges based only on a successful monorepo build.
  7. Agree secure publication. Confirm @ansible namespace ownership, authorized maintainers, CI publisher identity, provenance, dependency and license checks, package-content checks, and release approval with the relevant maintainers. These controls are not established by this inventory.
  8. Onboard dynamic plugins separately. The proposed RHDH path uses export overlays for OCI packaging and validation. SDK libraries themselves do not become installable dynamic plugins. Onboarding access and packaging ownership remain to be confirmed before implementing a release workflow.

The author guide and out-of-tree ADR predate this publication work. Update their in-tree preview restrictions and provisional install instructions together with an accepted external-consumption contract, rather than treating this inventory as an already available npm installation path.

Validation artifact provenance

CI generates an SPDX SBOM for each candidate archive with a pinned Syft version. PR validation remains read-only and uploads diagnostics and SBOMs without candidate tarballs. Trusted pushes or manual runs on main create Sigstore-backed build provenance covering archive, SBOM, index, and report digests before uploading the candidates. Attestation failure blocks candidate upload. Checkout credential persistence is disabled. These controls identify validation artifact origin and integrity; they do not approve npm publication or establish production readiness.

SBOMs cover the delivered package contents, with cataloged npm identity and version checked against the validation report. External consumer dependency resolution and vulnerability/license review remain separate requirements. See scripts/sdk-package-validation/README.md for local generation and verification. The first trusted signing run can be exercised after these workflows reach main.