In your Vite Project

If you have a Vite/React/TypeScript project you can integrate Keycloakify directly inside it.

In this guide we're going to work with a vanilla Vite project.

Before anything make sure to commit all your pending changes so you can easily revert changes if need be.

Let's start by installing Keycloakify (and optionally Storybook) to our project:

yarn add keycloakify@next
yarn add --dev storybook @storybook/react @storybook/react-vite

Next we want to repatriate the relevent files from the starter template into our project:

cd my-react-app
git clone tmp
mv tmp/src src/keycloak-theme
mv tmp/.storybook .
rm -r tmp
rm src/keycloak-theme/vite-env.d.ts
mv src/keycloak-theme/main.tsx src/main.tsx

Now you want to modify your entry point so that:

  • If the kcContext global is defined, render your Keycloakify theme

  • Else, reder your App as usual.

/* eslint-disable react-refresh/only-export-components */
import { createRoot } from "react-dom/client";
import { StrictMode, lazy, Suspense } from "react";

// The following block can be uncommented to test a specific page with `yarn dev`
// Don't forget to comment back or your bundle size will increase
import { getKcContextMock } from "./keycloak-theme/login/KcPageStory";

if (import.meta.env.DEV) {
    window.kcContext = getKcContextMock({
        pageId: "register.ftl",
        overrides: {}

const KcLoginThemePage = lazy(() => import("./keycloak-theme/login/KcPage"));
const KcAccountThemePage = lazy(() => import("./keycloak-theme/account/KcPage"));
const App = lazy(() => import("./App"));

            {(() => {
                switch (window.kcContext?.themeType) {
                    case "login":
                        return <KcLoginThemePage kcContext={window.kcContext} />;
                    case "account":
                        return <KcAccountThemePage kcContext={window.kcContext} />;
                return <App />;

declare global {
    interface Window {
            | import("./keycloak-theme/login/KcContext").KcContext
            | import("./keycloak-theme/account/KcContext").KcContext;

You also need to use Keycloakify's Vite plugin. Here we don't provide any build options but you probably at least want to define keycloakVersionTargets.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [

Finally you want to add to your package.json a script for building the theme and another one to start storybook.

  "name": "my-react-app",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview",
    "build-keycloak-theme": "npm run build && keycloakify build",
    "storybook": "storybook dev -p 6006"
  // ...

That's it, your project is ready to go!

You can run npm run build-keycloak-theme, the JAR distribution of your Keycloak theme will be generated in dist_keycloak.

You're now able to use all the Keycloakify commands (npx keycloakify --help) from the root of your project.

If you're currently using keycloak-js or react-oidc-context to manage user authentication in your app you might want to checkout oidc-spa, the alternative from the Keycloakify team.

If you have any issues reach out on Discord! We're here to help!

๐ŸงชTesting your Theme๐ŸŽจCustomization Strategies

Last updated