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.


Let's start by installing Keycloakify (and optionally Storybook) to our project:
yarn add keycloakify
yarn add --dev storybook @storybook/react @storybook/react-vite
Next we want to repatriate the relevant files from the starter template into our project:
cd my-react-app
git clone https://github.com/keycloakify/keycloakify-starter tmp
mv tmp/src src/keycloak-theme
mv tmp/.storybook .
rm -rf 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";
import { KcPage, type KcContext } from "./keycloak-theme/kc.gen";
const App = lazy(() => import("./App"));
// 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: {}
});
}
*/
createRoot(document.getElementById("root")!).render(
<StrictMode>
{window.kcContext ? (
<KcPage kcContext={window.kcContext} />
) : (
<Suspense>
<App />
</Suspense>
)}
</StrictMode>
);
declare global {
interface Window {
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";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
react(),
keycloakify({
accountThemeImplementation: "none"
})
],
})
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!
Last updated
Was this helpful?