From dcba493bb9ac3f225f76c207d218e7d5a16b48ad Mon Sep 17 00:00:00 2001 From: Garrone Joseph Date: Sat, 23 Apr 2022 17:49:00 +0000 Subject: [PATCH] GitBook: [#9] No subject --- README.md | 6 --- how-to-use.md | 142 ++++++++++++++++++++++++++++++-------------------- page-1.md | 22 +------- 3 files changed, 86 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index ca1885811..5af3ec220 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,6 @@ Windows users will haver to use it via [WSL](https://docs.microsoft.com/en-us/wi This tool will be maintained to stay compatible with every Keycloak version starting from [Keycloak Version 11](https://github.com/keycloak/keycloak/releases/tag/11.0.3). However, the default pages you will get (before you customize them) will always be the ones of Keycloak [v11.0.3](https://github.com/keycloak/keycloak/releases/tag/11.0.3). - -You can download the version of the builtin theme the Keycloakify's components are based on with the following command: - -```bash -npx -p keycloakify download-builtin-keycloak-theme -``` {% endhint %} ### Supported Keycloak version diff --git a/how-to-use.md b/how-to-use.md index 20fb32f36..99896bd9a 100644 --- a/how-to-use.md +++ b/how-to-use.md @@ -1,10 +1,8 @@ -# 👨💻 Quick start +# How to use -{% hint style="success" %} -It's a good idea to first read this quick start section to get the idea of how Keycloakify works however we recommend you start hacking from [**the demo setup**](https://github.com/garronej/keycloakify-demo-app) instead of setting up Keycloakify from scratch. -{% endhint %} +### Setting up the build tool -``` +```bash yarn add keycloakify @emotion/react ``` @@ -24,86 +22,75 @@ On the console will be printed all the instructions about how to load the genera {% tabs %} {% tab title="CSS Only customization" %} -The first approach is to only customize the style of the default Keycloak login theme by providing your own class names. - -{% hint style="info" %} -The keycloakify components are a plain React translation of the default theme that comes with Keycloak v11.0.3. +The first approach is to only customize the style of the default Keycloak login by providing your own class names. -You can download the FTL/CSS source files the components are based on with the following command `npx -p keycloakify download-builtin-keycloak-theme` and selecting version 11.0.3. -{% endhint %} +If you have created a new React project specifically to create a Keycloak theme and nothing else then your index should look something like: `src/index.tsx` ```tsx +import { App } from ".//App"; import { KcApp, defaultKcProps, getKcContext } from "keycloakify"; -//We assume the file contains: ".my-class { color: red; }" -import "./index.css"; +import { css } from "tss-react/@emotion/css"; const { kcContext } = getKcContext(); -if( kcContex === undefined ){ - throw new Error( - "This app is a Keycloak theme" + - "It isn't meant to be deployed outside of Keycloak" - ); -} +const myClassName = css({ "color": "red" }); reactDom.render( , document.getElementById("root"), ); ``` -The above snippet of code assumes you are in a react project wich only purpose is to be a Keycloak theme. - -But if you want to make your keycloak theme an integral part of a preexisting React app you would apply the following modification to the above snipet: - -```diff -+import { App } from " : - , - document.getElementById("root"), -); -``` +If you share a unique project for your app and the Keycloak theme, your index should look more like this: -![Result: MYREALM is red](https://user-images.githubusercontent.com/6702424/114326299-6892fc00-9b34-11eb-8d75-85696e55458f.png) +`src/index.tsx` -#### Real world example +```tsx +import { App } from ".//App"; +import { KcApp, defaultKcProps, getKcContext } from "keycloakify"; +import { css } from "tss-react/@emotion/css"; + +const { kcContext } = getKcContext(); + +const myClassName = css({ "color": "red" }); + +reactDom.render( + // Unless the app is currently being served by Keycloak + // kcContext is undefined. + kcContext !== undefined ? ( + + ) : ( + + ), // Your actual app + document.getElementById("root"), +); +``` -To give you an idea of what you can already achieve by only customizing the style the style, +_result:_\ +![](https://user-images.githubusercontent.com/6702424/114326299-6892fc00-9b34-11eb-8d75-85696e55458f.png) -Here is [**the code**](https://github.com/InseeFrLab/onyxia-web/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/components/KcApp.tsx) that produces: +Example of a customization using only CSS: [here](https://github.com/InseeFrLab/onyxia-web/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/components/KcApp.tsx) (the [index.tsx](https://github.com/InseeFrLab/onyxia-web/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/index.tsx#L89-L94) ) and the result you can expect: -![Results obtained with CSS only customization of the default theme](https://github.com/InseeFrLab/keycloakify/releases/download/v0.3.8/keycloakify\_after.gif) +![](https://github.com/InseeFrLab/keycloakify/releases/download/v0.3.8/keycloakify\_after.gif) {% endtab %} {% tab title="Component level customization" %} + + If you want to go beyond only customizing the CSS you can re-implement some of the pages or even add new ones. If you want to go this way checkout the demo setup provided [here](https://github.com/garronej/keycloakify-demo-app/tree/look\_and\_feel). If you prefer a real life example you can checkout [onyxia-web's source](https://github.com/InseeFrLab/onyxia-web/tree/main/src/ui/components/KcApp). The web app is in production [here](https://datalab.sspcloud.fr). @@ -117,4 +104,45 @@ Main takeaways are: {% endtab %} {% endtabs %} -### +#### + +#### Hot reload + +Rebuild the theme each time you make a change to see the result is not practical. If you want to test your login screens outside of Keycloak you can mock a given `kcContext`: + +```tsx +import { + KcApp, + defaultKcProps, + getKcContext +} from "keycloakify"; + +const { kcContext } = getKcContext({ + "mockPageId": "login.ftl" +}); + +reactDom.render( + + document.getElementById("root") +); +``` + +Then `yarn start`, you will see your login page. + +Checkout [this concrete example](https://github.com/garronej/keycloakify-demo-app/blob/main/src/index.tsx) + +### Enable loading in a blink of an eye of login pages ⚡ (--external-assets) + +By default the theme generated is standalone. Meaning that when your users reach the login pages all scripts, images and stylesheet are downloaded from the Keycloak server.\ +If you are specifically building a theme to integrate with an app or a website that allows users to first browse unauthenticated before logging in, you will get a significant performance boost if you jump through those hoops: + +* Provide the url of your app in the `homepage` field of package.json. [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/package.json#L2) or in a `public/CNAME` file. [ex](https://github.com/garronej/keycloakify-demo-app/blob/main/public/CNAME). +* Build the theme using `npx build-keycloak-theme --external-assets` [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/.github/workflows/ci.yaml#L21) +* Enable [long-term assets caching](https://create-react-app.dev/docs/production-build/#static-file-caching) on the server hosting your app. +* Make sure not to build your app and the keycloak theme separately and remember to update the Keycloak theme every time you update your app. +* Be mindful that if your app is down your login pages are down as well. + +Checkout a complete setup [here](https://github.com/garronej/keycloakify-demo-app#about-keycloakify) diff --git a/page-1.md b/page-1.md index 7eaad3a0e..6f8b4979f 100644 --- a/page-1.md +++ b/page-1.md @@ -1,22 +1,2 @@ ---- -description: Enable loading in a blink of an eye of login pages with --external-assets ---- +# Page 1 -# ⚡ Performance optimization - -{% hint style="warning" %} -This only apply if your theme is integrated to to a React app. - -If your theme Keycloak theme is a standalone react project you can ignore this section. -{% endhint %} - -By default the theme generated is standalone. Meaning that when your users reach the login pages all scripts, images and stylesheet are downloaded from the Keycloak server.\ -If you are specifically building a theme to integrate with an app or a website that allows users to first browse unauthenticated before logging in, you will get a significant performance boost if you jump through those hoops: - -* Provide the url of your app in the `homepage` field of package.json. [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/package.json#L2) or in a `public/CNAME` file. [ex](https://github.com/garronej/keycloakify-demo-app/blob/main/public/CNAME). -* Build the theme using `npx build-keycloak-theme --external-assets` [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/.github/workflows/ci.yaml#L21) -* Enable [long-term assets caching](https://create-react-app.dev/docs/production-build/#static-file-caching) on the server hosting your app. -* Make sure not to build your app and the keycloak theme separately and remember to update the Keycloak theme every time you update your app. -* Be mindful that if your app is down your login pages are down as well. - -Checkout a complete setup [here](https://github.com/garronej/keycloakify-demo-app#about-keycloakify)