⬆️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 suposed to be setup.

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

• An app using Keycloakify v5
• The same app after upgrade to v6

i18n: Adding i18n messages keys

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

Keycloakify v6 now has a proper i18n api.

🌎i18n: msg(...)

Tems and conditions

The message termsTitle (Terms and Conditions in en.ts) was repmaced 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 perfomed an modification at the component level of the Terms.tsx component be mindfull that we now use an Evt to re render when the terms Markdown have been downloaded.

sill-web/Terms.tsx at main · etalab/sill-webGitHub

Example of component level configuration of the Terms page

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
 });

Cloud IAM - Keycloak Identity and Access Management as a Service

Feeling overwhelmed? Check out our exclusive sponsor's Cloud IAM consulting services to simplify your experience.