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:

• 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 internationalized message.

Keycloakify v6 now has a proper i18n api.

https://github.com/keycloakify/docs.keycloakify.dev/blob/changelog/broken-reference/README.md

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.

https://github.com/etalab/sill-web/blob/main/src/ui/components/KcApp/Terms.tsxgithub.com

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

https://cloud-iam.com/?mtm_campaign=keycloakify-deal&mtm_source=keycloakify-doc-migration-guides-readme-1cloud-iam.com

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