@andreyyolkin/keycloakify-vue

@andreyyolkin/keycloakify-vue

Vue 3 components for building Keycloak login themes with Keycloakify.

@andreyyolkin/keycloakify-vue is a community Vue 3 port of Keycloakify's UI layer, mirroring the architecture of @keycloakify/svelte. It reuses Keycloakify's framework-agnostic build tooling and core logic via a peer dependency — only the Vue UI layer (layer 3) is reimplemented here. You write your Keycloak theme in Vue; keycloakify handles the build + jar packaging unchanged.

Status

Installation

npm install --save-dev @andreyyolkin/keycloakify-vue

Peer dependencies: keycloakify ^11.15.1 and vue ^3.5.0 must be installed in your project.

The easiest way to get started is the official starter template:

• keycloakify-starter-vue — a ready-to-use Vite + Vue project wired to @andreyyolkin/keycloakify-vue, analogous to keycloakify-starter-svelte.

What's Included

• DefaultPage — top-level dispatcher component that routes all 38 login pageId values to the correct page component.
• Template — the outer page shell (header, info/error alerts, social providers, language switcher).
• Per-page components — importable individually from @andreyyolkin/keycloakify-vue/login/pages/*.vue (e.g. Login.vue, Register.vue, LoginOtp.vue, …).
• UserProfileFormFields — full dynamic user-profile form suite used by Register, LoginUpdateProfile, and IdpReviewUserProfile.
• i18nBuilder — factory for wiring Keycloakify's noJsx i18n engine into Vue (returns msg() / advancedMsg() that produce sanitized VNodes).

  withCustomTranslations must be called from a plain .ts/.tsx/.js file, never from a .vue SFC. At build time, keycloakify's generateMessageProperties step statically scans your theme source for a withCustomTranslations({...}) call to produce the server-side messages_<lang>.properties bundle — but it only scans files matching /\.(js|ts|tsx)$/, so a call placed inside a <script setup> block of a .vue file is silently skipped and those keys never reach the server bundle (client-side msg() still works, which can make the gap easy to miss). Keep your i18nBuilder(...).withCustomTranslations(...) call in a dedicated i18n.ts (as in this repo's stories/login/i18n.ts) and import it from your .vue components instead.

• Account theme — importable from @andreyyolkin/keycloakify-vue/account: its own DefaultPage + Template, the 7 account pages at @andreyyolkin/keycloakify-vue/account/pages/*.vue, and an account i18nBuilder.
• bin handlers — _keycloakify-custom-handler delegates update-kc-gen, eject-page, add-story, and initialize-account-theme so the keycloakify CLI treats your project as a Vue theme.

Usage

Clone or scaffold from the starter for the full wiring. At its core a consumer project has a KcPage.vue that looks like:

<script setup lang="ts">
import { DefaultPage } from '@andreyyolkin/keycloakify-vue';
import type { KcContext } from './KcContext';
import { useI18n } from './i18n';
import Template from '@andreyyolkin/keycloakify-vue/login/Template.vue';

const props = defineProps<{ kcContext: KcContext }>();
const { i18n } = useI18n({ kcContext: props.kcContext });
</script>

<template>
  <DefaultPage
    :kcContext
    :i18n
    :Template
  />
</template>

How It Works / Relationship to Keycloakify

Keycloakify is built in three layers:

1. Build tooling / CLI (keycloakify/bin, keycloakify/vite-plugin) — framework-agnostic. Reads a built SPA, rewrites asset paths to FreeMarker variables, generates .ftl templates, packages the theme .jar.
2. Core logic (KcContext types, i18n/noJsx, getUserProfileApi, kcClsx, kcSanitize) — deliberately framework-agnostic.
3. UI components — the only framework-coupled layer.

@andreyyolkin/keycloakify-vue reuses layers 1 and 2 unchanged (via the keycloakify peer dependency) and reimplements layer 3 in Vue 3.

Distribution: the package ships raw .vue single-file components plus .d.ts types. Your project's Vite + @vitejs/plugin-vue compiles them — no pre-bundled JS is shipped.

Contributing

git clone https://github.com/AndreyYolkin/keycloakify-vue
git clone https://github.com/AndreyYolkin/keycloakify-starter-vue

cd keycloakify-vue
yarn install
yarn link-in-starter   # links the built package into the starter

Changes to the library are reflected in the starter after yarn build (or yarn watch).

Issues and pull requests are welcome at github.com/AndreyYolkin/keycloakify-vue.

License

MIT