GitBook: [#9] No subject

keycloakify · Apr 23, 2022 · dcba493 · dcba493
1 parent 9e7dfe1
commit dcba493
Show file tree

Hide file tree

Showing 3 changed files with 86 additions and 84 deletions.
diff --git 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
@@ -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. &#x20;
+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 "./<wherever>/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(
     <KcApp
         kcContext={kcContext}
         {...{
             ...defaultKcProps,
-            "kcHeaderWrapperClass": "my-class",
+            "kcHeaderWrapperClass": myClassName,
         }}
     />,
     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 "<you know where";
- import { KcApp, defaultKcProps, getKcContext } from "keycloakify";
- import "./index.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"
--    );
--}
-
- reactDom.render(
-+    kcContext === undefined ?
-+        <App /> :
-         <KcApp
-             kcContext={kcContext}
-             {...{
-                 ...defaultKcProps,
-                 "kcHeaderWrapperClass": myClassName,
-             }}
-         />,
-     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 "./<wherever>/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 ? (
+        <KcApp
+            kcContext={kcContext}
+            {...{
+                ...defaultKcProps,
+                "kcHeaderWrapperClass": myClassName,
+            }}
+        />
+    ) : (
+        <App />
+    ), // 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:&#x20;
+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(
+        <KcApp
+            kcContext={kcContextMocks.kcLoginContext}
+            {...defaultKcProps}
+        />
+    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
@@ -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. &#x20;
-
-If your theme Keycloak theme is a standalone react project you can ignore this section.&#x20;
-{% 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)