v11
GitHubHomeStorybookStarter TemplateAlternative to keycloak-js

⬆️v5 -> v6

Migration guide from v5 to v6

Main script renamed to keycloakify

You can search and replace build-keycloak-theme -> keycloakify in your project.

package.json

 "scripts": {
     "start": "react-scripts start",
     "build": "react-scripts build",
-    "keycloak": "yarn build && build-keycloak-theme"
+    "keycloak": "yarn build && keycloakify"
 },
 "dependencies": {
-    "tss-react": "^3.6.0",
-    "keycloakify": "^5.7.0",
+    "keycloakify": "^6.8.8"
 }

.github/workflows/ci.yaml

-- run: npx build-keycloak-theme
+- run: npx keycloakify
-- run: npx build-keycloak-theme --external-assets
+- run: npx keycloakify --external-assets

Components exported using default export

In order to enable you to use React.lazy(), Keycloakify components are now exported with default exports instead of named exports.

-import { KcApp, defaultKcProps, getKcContext } from "keycloakify";
+import KcApp, { defaultKcProps, getKcContext } from "keycloakify";

-import { Login } from "keycloakify/lib/components/Login";
+import Login from "keycloakify/lib/components/Login";

Once you're at it, it might be a good time to update your app to use <Suspense/> and React.lazy() in order to reduce your bundle size. See keycloakify-starter (CSS only) or keycloakify-advanced-starter (component level customization) to see how it's supposed to be setup.

You can also have a look at a real world migration:

i18n: Adding i18n messages keys

In v5 and prior, Keycloakify only provided a very hacky way of customizing internationalized message.

Keycloakify v6 now has a proper i18n api.

Internationalization

Terms and conditions

The message termsTitle (Terms and Conditions in en.ts) was replaced by a blank string in v5. If you want to do the same in v6 you have to use the new i18n API.

 useDownloadTerms({
   kcContext,
   "downloadTermMarkdown": async ({ currentKcLanguageTag }) => {

-     kcMessages[currentKcLanguageTag].termsTitle = "";

     const markdownString = await fetch((() => {
       switch (currentKcLanguageTag) {
         case "fr": return tos_fr_url;
         default: return tos_en_url;
       }
     })()).then(response => response.text());

     return markdownString;

   }
 });

 const i18n = useI18n({
    kcContext,
    "extraMessages": {
        "en": {
+            "termsTitle": "",
        },
        "fr": {
            /* spell-checker: disable */
+           "termsTitle": "",
            /* spell-checker: enable */
        }
    }
});

If you have performed a modification at the component level of the Terms.tsx component be mindful that we now use an Evt to re render when the terms Markdown have been downloaded.

useFormValidationSlice()

useFormValidationSlice() now require you to pass a i18n object, see I18n API.

 import { useFormValidationSlice } from "keycloakify";

 const {
     formValidationState,
     formValidationReducer,
     attributesWithPassword
 } = useFormValidationSlice({
     kcContext,
     passwordValidators,
+    i18n
 });