Keycloak Onboarding UI

Standalone theme package for Keycloak. It ships an Admin Console theme (Theme.Type.ADMIN) named keycloak-onboarding-ui: FreeMarker shell + Vite-built resources/, same pattern as the stock keycloak.v2 admin theme.

Keycloak UI bits come from the published npm packages @keycloak/keycloak-ui-shared and @keycloak/keycloak-admin-client (see package.json). Use a release line that matches your server (for example ^26.6.1 for Keycloak 26.6.x) so APIs stay aligned.

Keycloak only loads classpath themes from theme/{themeName}/{type}/ (see ClassLoaderTheme in the server). Types must be one of login, account, admin, email, welcome, common. A separate theme name avoids clobbering the built-in keycloak.v2 entry in the theme map and shows up as its own row in Realm settings → Themes → Admin theme.

The Admin Console index.ftl must include the same importmap as the stock admin theme so react, react/jsx-runtime, and react-dom resolve to Keycloak’s resourceCommonUrl vendor bundles. The production Vite build externalizes those packages (see vite.config.ts); without the import map, or with React bundled inside the theme while admin-ui chunks import bare react, you get two React copies and hook errors such as useRef / null internal dispatcher.

Dependencies

Install from the registry (no local link: to the Keycloak repo):

pnpm install

Keep react-hook-form on the same version that @keycloak/keycloak-ui-shared depends on (currently 7.70.0, pinned in package.json). A newer minor (e.g. ^7.70 resolving to 7.74) can install a second copy and break FormProvider / useFormContext (control is null in the browser).

Build

pnpm install && pnpm build

Artifacts:

• target/classes/theme/keycloak-onboarding-ui/admin/resources/ — JS/CSS from Vite
• target/classes/theme/keycloak-onboarding-ui/admin/ — index.ftl, theme.properties, messages
• target/classes/META-INF/keycloak-themes.json — registers theme name keycloak-onboarding-ui, type admin

This tree matches the layout the Keycloak Admin Console theme module uses under target/classes, so you can package it as a JAR or copy it into a server themes/ directory.

To produce a theme JAR for Keycloak’s providers/ folder (ZIP layout, no JDK jar tool required):

pnpm package-jar

Artifact: target/keycloak-onboarding-ui-theme.jar. Copy it to $KC_HOME/providers/, run bin/kc.sh build, then start the server.

Install on a Keycloak server

1. Build with pnpm build (or pnpm package-jar, which runs build first).
2. Deploy the theme:
   • JAR in providers/: copy target/keycloak-onboarding-ui-theme.jar into $KC_HOME/providers/, then bin/kc.sh build, then start Keycloak.
   • Files under themes/: merge target/classes/theme/keycloak-onboarding-ui/ into $KC_HOME/themes/keycloak-onboarding-ui/, and ensure META-INF/keycloak-themes.json from target/classes/ is on the classpath (same JAR layout or merged under themes/ per Keycloak docs).
3. In the Admin Console, open Realm settings → Themes and set Admin theme to keycloak-onboarding-ui. Save.

ADMIN_V2 must be enabled (default on current Keycloak); the Admin theme list is built from successfully resolved Theme.Type.ADMIN themes only.

Using as a drop-in replacement for the stock keycloak.v2 admin assets

This project registers a separate theme name so the picker stays unambiguous. To overwrite the stock keycloak.v2 admin static files instead (experiments only):

1. Run pnpm build.
2. Back up the server’s themes/keycloak.v2/admin/resources/ (or the copy inside the distribution JAR).
3. Copy the contents of target/classes/theme/keycloak-onboarding-ui/admin/resources/ into themes/keycloak.v2/admin/resources/.
4. Copy index.ftl, theme.properties, and messages/ from target/classes/theme/keycloak-onboarding-ui/admin/ into themes/keycloak.v2/admin/.

Development server

pnpm dev

Runs Vite on port 5176 with API calls against the serverBaseUrl configured in src/App.tsx (adjust for your Keycloak URL).