8000 Add UiScriptProvider for custom admin console pages by edewit · Pull Request #54586 · keycloak/keycloak · GitHub
[go: up one dir, main page]

Skip to content

Add UiScriptProvider for custom admin console pages - #54586

Open
edewit wants to merge 2 commits into
keycloak:mainfrom
edewit:issue-54583-ui-script-provider
Open

edewit wants to merge 2 commits into
keycloak:mainfrom
edewit:issue-54583-ui-script-provider

Conversation

@edewit
@edewit edewit commented Nov 3, 2026
Copy link
Copy Markdown
Contributor

Summary

  • Add UiScriptProvider / ui-script SPI under the experimental declarative-ui feature for nav items backed by a dynamically imported ES module
  • Expose script providers via Server Info componentTypes with metadata.url
  • Admin console mounts default({ realm, i18n, adminClient }) on navigate and unmounts on leave

Closes #54583

Introduce a declarative-ui SPI that exposes a nav item and dynamically
imports a Java-declared ES module, mounting the returned element with
realm, i18n, and adminClient context.

Closes keycloak#54583

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>
Copilot AI balanced review requested due to automatic review settings November 3, 2026 13:03
@edewit
edewit requested review from a team as code owners November 3, 2026 13:03
Copilot AI left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The effect omits providerId from its dependencies, so switching between providers with the same module URL leaves the previous element mounted and skips the new page’s factory.

1 open issue
What changed in this PR

Adds script-backed admin console pages to the experimental declarative UI extension system, allowing providers to supply custom interfaces without forking the console.

Changes:

  • Introduces the feature-gated ui-script SPI and exposes module URLs through Server Info.
  • Adds Configure navigation and routes for script-backed pages.
  • Dynamically imports modules, mounts their returned elements, and removes them on exit.
File Description
services/​src/​main/​java/​org/​keycloak/​services/​resources/​admin/​info/​ServerInfoAdminResource.java Exposes script provider IDs and module URLs.
server-spi-private/​src/​main/​resources/​META-INF/​services/​org.keycloak.provider.Spi Registers the new SPI.
server-spi-private/​src/​main/​java/​org/​keycloak/​services/​ui/​extend/​UiScriptSpi.java Defines the feature-gated ui-script SPI.
server-spi-private/​src/​main/​java/​org/​keycloak/​services/​ui/​extend/​UiScriptProviderFactory.java Defines the module URL and factory contract.
server-spi-private/​src/​main/​java/​org/​keycloak/​services/​ui/​extend/​UiScriptProvider.java Adds the script-backed page provider interface.
js/​apps/​admin-ui/​src/​PageNav.tsx Lists script providers under Configure.
js/​apps/​admin-ui/​src/​page/​ScriptPage.tsx Handles module loading, mounting, and cleanup.
js/​apps/​admin-ui/​src/​page/​routes.tsx Adds script-page routing and URL generation.
js/​apps/​admin-ui/​src/​page/​constants.ts Adds the script provider lookup key.
js/​apps/​admin-ui/​src/​components/​bread-crumb/​PageBreadCrumbs.tsx Excludes the intermediate script path from breadcrumbs.

Review effort: Balanced

Copilot AI left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Test coverage is missing for Server Info provider metadata and feature gating, and for asynchronous script mounting, context passing, and cleanup during navigation.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Low severity Test async UI mounting and navigation cleanup

js/​apps/​admin-ui/​src/​page/​ScriptPage.tsx:58

The new asynchronous mounting lifecycle has no admin UI test coverage. Add a test with a controllable module import that verifies the context passed to the module, removal of its element on navigation away, and prevention of mounting when navigation occurs before the import completes.

Low severity Add Server Info coverage for declarative UI providers

services/​src/​main/​java/​org/​keycloak/​services/​resources/​admin/​info/​ServerInfoAdminResource.java:241

The new Server Info serialization branch has no test registering a UiScriptProviderFactory; the existing ServerInfoTest exercises configured providers instead. Add integration coverage under tests/ that verifies the provider ID and metadata.url with declarative-ui enabled, and verifies that the SPI is absent when the feature is disabled.

1 resolved since last review

Review effort: Balanced

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Erik Jan de Wit <edewit@redhat.com>
Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>
@edewit
edewit force-pushed the issue-54583-ui-script-provider branch from 3a5c702 to 8ff921f Compare November 4, 2026 08:34
Copilot AI balanced review requested due to automatic review settings November 4, 2026 08:34
Copilot AI left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Automated coverage is missing for module-loading context, cleanup, and stale imports, as well as feature-gated UI script provider discovery and serialization.

2 open issues

Review effort: Balanced

Comment on lines +54 to +58
const module = (await import(/* @vite-ignore */ url)) as UiScriptModule;
if (!active.current) {
return;
}
mounted = module.default({ realm, i18n, adminClient });
Comment on lines +237 to +241
} else if (pi instanceof UiScriptProviderFactory scriptFactory) {
ComponentTypeRepresentation rep = new ComponentTypeRepresentation();
rep.setId(pi.getId());
Map<String, Object> metadata = new HashMap<>();
metadata.put("url", scriptFactory.getUrl());
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add UiScriptProvider for custom admin console pages via declarative UI

2 participants

0