This is the documentation for v10, checkout the latest version
Keycloakify
HomeGitHubStartersStorybookDiscordKeycloak-js Alternative
v10
  • Keycloakify
  • Release Notes & Upgrade Instructions
  • FAQ
v10
  • ๐Ÿ‘จโ€๐Ÿ’ปQuick start
  • ๐ŸงชTesting your Theme
    • In Storybook
    • In a Keycloak Docker Container
    • With Vite or Webpack in dev mode
  • ๐Ÿ”ฉIntegrating Keycloakify in your Codebase
    • In your React Project
      • In your Vite Project
      • In your Webpack Project
    • As a Subproject of your Monorepo
      • Turborepo
      • Nx Integrated Monorepo
      • Package Manager Workspaces
  • ๐ŸŽจCustomization Strategies
    • CSS Level Customization
      • Basic example
      • Removing the default styles
      • Applying your own classes
      • Page specific styles
      • Using Tailwind
      • Using custom assets
        • .css, .sass or .less
        • CSS-in-JS
    • Component Level Customization
      • Using custom assets
  • ๐Ÿ–‹๏ธCustom Fonts
  • ๐ŸŒŽInternationalization and Translations
  • ๐ŸŽญTheme Variants
  • ๐Ÿ“Customizing the Register Page
  • ๐Ÿ‘คAccount Theme
    • Single-Page
    • Multi-Page
  • ๐Ÿ“„Terms and conditions
  • ๐Ÿ–‡๏ธStyling a Custom Page Not Included In Base Keycloak
  • ๐Ÿ”งAccessing the Server Environment Variables
  • ๐ŸŽฏTargetting Specific Keycloak Versions
  • ๐Ÿ“งEmail Customization
  • ๐Ÿš›Passing URL Parameters to your Theme
  • ๐ŸคตAdmin theme
  • ๐Ÿ“ฅImporting the JAR of Your Theme Into Keycloak
  • ๐Ÿ”›Enabling your Theme in the Keycloak Admin Console
  • ๐Ÿค“Taking ownership of the kcContext
  • ๐Ÿ“–Configuration Options
    • --project
    • keycloakVersionTargets
    • environmentVariables
    • themeName
    • startKeycloakOptions
    • themeVersion
    • postBuild
    • XDG_CACHE_HOME
    • kcContextExclusionsFtl
    • keycloakifyBuildDirPath
    • groupId
    • artifactId
    • Webpack specific options
      • projectBuildDirPath
      • staticDirPathInProjectBuildDirPath
      • publicDirPath
  • FAQ & HELP
    • ๐Ÿ˜žCan't identify the page to customize?
    • ๐Ÿค”How it Works
    • ๐Ÿ˜–Some values you need are missing from in kcContext type definitions?
    • โ“Can I use it with Vue or Angular
      • Angular
    • โš ๏ธLimitations
    • ๐Ÿ›‘Errors Keycloak in Logs
    • ๐Ÿ™‹How do I add extra pages?
    • ๐Ÿค“Can I use react-hooks-form?
    • ๐Ÿš€Redirecting you users to the login/register pages
    • ๐Ÿ’ŸContributing
    • โฌ†๏ธMigration Guides
      • โฌ†๏ธv9 -> v10
      • โฌ†๏ธCRA -> Vite
      • โฌ†๏ธv8 -> v9
      • โฌ†๏ธv7 -> v8
      • โฌ†๏ธv6 -> v7
      • โฌ†๏ธv6.x -> v6.12
      • โฌ†๏ธv5 -> v6
    • ๐ŸชGoogle reCaptcha and End of third-party Cookies
    • ๐Ÿ”–Accessing the Realm Attributes
  • โญSponsors
Powered by GitBook
On this page

Was this helpful?

  1. Integrating Keycloakify in your Codebase
  2. In your React Project

In your Webpack Project

PreviousIn your Vite ProjectNextAs a Subproject of your Monorepo

Last updated 2 months ago

Was this helpful?

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

In this guide we're going to work with a vanilla 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
yarn add --dev rimraf storybook @storybook/react @storybook/react-vite
pnpm add keycloakify
pnpm add --dev rimraf storybook @storybook/react @storybook/react-vite
bun add keycloakify
bun add --dev rimraf storybook @storybook/react @storybook/react-vite
npm install --save keycloakify
npm install --save-dev rimraf storybook @storybook/react @storybook/react-vite
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, render your App as usual.

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

Question:

Why do my main application and Keycloak theme share the same entry point?

Answer:

To simplify the build process. If you don't want it to negatively impact the performance of your application, it's essential to understand the following points:

  • Different Contexts: The application (App) and Keycloak page (KcPage) are mounted in very different contexts. Avoid sharing providers between the two at the main.tsx file level. The true entry point of your application is the App component, while the entry point for your Keycloak theme is the KcPage component. Be careful about what code is shared between them.

  • Responsibility of main.tsx: The main.tsx file should only determine the context (either the application or Keycloak) and mount the appropriate component (App or KcPage). It should not contain any substantial logic or dependencies.

  • Performance Considerations: Keep main.tsx as lightweight as possible to avoid increasing the initial load time of both your main application and login pages. For example, do not load any state management libraries like redux-toolkit at this level.

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": {
        "prestart": "keycloakify update-kc-gen && keycloakify copy-keycloak-resources-to-public",
        "start": "react-scripts start",
        "prestorybook": "npm run prestart",
        "storybook": "storybook dev -p 6006",
        "prebuild": "keycloakify update-kc-gen",
        "build": "react-scripts build",
        "postbuild": "rimraf build/keycloakify-dev-resources",
        "build-keycloak-theme": "npm run build && keycloakify build",
        "format": "prettier . --write"
        // ...
    },
    "keycloakify": {
        "accountThemeImplementation": "none",
        "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 those values to reflect how webpack build your site in your project.

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

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

Next we want to repatriate the relevant files from into our project:

Leave accountThemeImplementation set to "none" for now. To initialize the account theme refer to .

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

If you're currently using or to manage user authentication in your app you might want to checkout , the alternative from the Keycloakify team.

If you have any issues ! We're here to help!

๐Ÿ”ฉ
the starter template
this guide
you can change this
keycloak-js
react-oidc-context
oidc-spa
reach out on Discord
๐ŸงชTesting your Theme
๐ŸŽจCustomization Strategies
Create React App
Creating a CRA project. You don't need to do that, just use your existing codebase.
Our codebase before involving Keycloakify
Sate of your codebase after bringing in Keycloakify's starter boilerplate code
Here you can see that in a CRA project, when we run npm run build the app distribution is generated in a build/ directory, this is why we use "projectBuildDirPath": "build". We can also see that all the assets of the app are gathered under a static/ directory this is why we use "staticDirPathInProjectBuildDirPath": "static". And finally we can see that everything we put in the public/ directory is copied over to the build/ directory when building so we use "publicDirPath": "public".