In your Webpack Project

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

In this guide we're going to work with a vanilla Create React App 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 rimraf storybook @storybook/react @storybook/react-vite

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

cd my-app
git clone https://github.com/keycloakify/keycloakify-starter-webpack tmp
mv tmp/src src/keycloak-theme
mv tmp/.storybook .
rm -rf tmp
rm src/keycloak-theme/react-app-env.d.ts
mv src/keycloak-theme/index.tsx src/index.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.

src/index.tsx
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 (process.env.NODE_ENV === "development") {
    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"));

createRoot(document.getElementById("root")!).render(
    <StrictMode>
        <Suspense>
            {(() => {
                switch (window.kcContext?.themeType) {
                    case "login":
                        return <KcLoginThemePage kcContext={window.kcContext} />;
                    case "account":
                        return <KcAccountThemePage kcContext={window.kcContext} />;
                }
                return <App />;
            })()}
        </Suspense>
    </StrictMode>
);

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

Finally you want to add some script for Keycloakify in you package.json and also let Keycloakify know about how your Webpack project is configured.

package.json
{
    "name": "my-app",
    "scripts": {
        "prestorybook": "keycloakify update-kc-gen && keycloakify copy-keycloak-resources-to-public",
        "storybook": "storybook dev -p 6006",
        "prestart": "npm run prestorybook",
        "start": "react-scripts start",
        "prebuild": "keycloakify update-kc-gen",
        "build": "react-scripts build",
        "postbuild": "rimraf build/keycloak-resources",
        "build-keycloak-theme": "npm run build && keycloakify build",
        // ...
    },
    "keycloakify": {
        "projectBuildDirPath": "build",
        "staticDirPathInProjectBuildDirPath": "static",
        "publicDirPath": "public"
    },
    // ...

Keycloakify has many build options that you can use, however projectBuildDirPath, staticDirPathInProjectBuildDirPath and publicDirPath are parameters specific to the use of Keycloakify in a Webpack context.

Theses are not preferences! If you're not using Create React App your Webpack configuration is probably different and you want to update thoses values to reflect how webpack build your site in your project.

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 can change this).

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