diff --git a/README.md b/README.md
index 72443bd6..900f3a41 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
- 🔏 Customize key cloak's pages as if they were part of your App 🔏
+ 🔏 Build Keycloak theme with React 🔏
@@ -18,80 +18,110 @@
# Motivations
-The problem:
+Keycloak provides [theme support](https://www.keycloak.org/docs/latest/server_development/#_themes) for web pages. This allows customizing the look and feel of end-user facing pages so they can be integrated with your applications.
+It involves, however, a lot of raw JS/CSS/[FTL]() hacking, and bundling the theme is not exactly straightforward.
+
+Beyond that, if you use Keycloak for a specific app you want your login page to be tightly integrated with it.
+Ideally, you don't want the user to notice when he is being redirected away.
+
+Trying to reproduce the look and feel of a specific app in another stack is not an easy task not to mention
+the cheer amount of maintenance that it involves.
- Without keycloakify:
+ Without keycloakify, users suffers from a harsh context switch, no fronted form pre-validation
-When we redirected to Keycloak the user suffers from a harsh context switch.
-Keycloak does offer a way to customize theses pages but it requires a lot of raw HTML/CSS hacking
-to reproduce the look and feel of a specific app. Not mentioning the maintenance cost of such an endeavour.
-Wouldn't it be great if we could just design the login and register pages as if they where part of our app?
-Here is `yarn add keycloakify` for you 🍸
+Wouldn't it be great if we could just design the login and register pages as if they were part of our app?
+Here is `keycloakify` for you 🍸
- With keycloakify:
+ With keycloakify:
+
-**TL;DR**: [Here](https://github.com/garronej/keycloakify-demo-app) is a Hello World React project with Keycloakify set up.
+If you already have a Keycloak custom theme, it can be easily ported to Keycloakify.
+
+---
+
- [Motivations](#motivations)
- [How to use](#how-to-use)
- [Setting up the build tool](#setting-up-the-build-tool)
- - [Developing your login and register pages in your React app](#developing-your-login-and-register-pages-in-your-react-app)
- - [Just changing the look](#just-changing-the-look)
+ - [Changing just the look of the default Keycloak theme](#changing-just-the-look-of-the-default-keycloak-theme)
- [Changing the look **and** feel](#changing-the-look-and-feel)
- [Hot reload](#hot-reload)
-- [Terms and conditions](#terms-and-conditions)
+ - [Enable loading in a blink of an eye of login pages ⚡ (--external-assets)](#enable-loading-in-a-blink-of-an-eye-of-login-pages----external-assets)
+- [Support for Terms and conditions](#support-for-terms-and-conditions)
- [GitHub Actions](#github-actions)
- [Requirements](#requirements)
- [Limitations](#limitations)
- [`process.env.PUBLIC_URL` not supported.](#processenvpublic_url-not-supported)
- [`@font-face` importing fonts from the `src/` dir](#font-face-importing-fonts-from-thesrc-dir)
- [Example of setup that **won't** work](#example-of-setup-that-wont-work)
- - [Workarounds](#workarounds)
+ - [Possible workarounds](#possible-workarounds)
- [Implement context persistence (optional)](#implement-context-persistence-optional)
-- [API Reference](#api-reference)
- - [The build tool](#the-build-tool)
# How to use
+
+**TL;DR**: [Here](https://github.com/garronej/keycloakify-demo-app) is a Hello World React project with Keycloakify set up.
## Setting up the build tool
+```bash
+yarn add keycloakify
+```
+
[`package.json`](https://github.com/garronej/keycloakify-demo-app/blob/main/package.json)
```json
-"homepage": "https://URL.OF/YOUR-APP"
-"dependencies": {
- "keycloakify": "^0.0.10"
-},
"scripts": {
"keycloak": "yarn build && build-keycloak-theme",
},
```
-`"homepage"` must be specified only if the url path is not `/`
-(Onl `/YOUR-APP` matters `URL.OF` don't have to be the actual domain)
-It is mandatory that you specify the url where your app will be available
-using the `homepage` field.
+```bash
+yarn keycloak # generate a keycloak-theme.jar
+```
-Once you've edited your `package.json` you can install your new
-dependency with `yarn install` and build the keycloak theme with
-`yarn keycloak`.
+On the console will be printed all the instructions about how to load the generated theme in Keycloak
-Once the build is complete instructions about how to load
-the theme into Keycloak are printed in the console.
+### Changing just the look of the default Keycloak theme
-## Developing your login and register pages in your React app
+The first approach is to only customize the style of the default Keycloak login by providing
+your own class names.
-### Just changing the look
-
-The first approach is to only arr/replace the default class names by your
-own.
+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,
+ kcContext
+} from "keycloakify";
+import { css } from "tss-react";
+const myClassName = css({ "color": "red" });
+
+reactDom.render(
+
+ document.getElementById("root")
+);
+```
+
+If you have a unique project for your app and the Keycloak theme, your index should look
+more like this:
+
+`src/index.tsx`
+```tsx
import { App } from ".//App";
import {
KcApp,
@@ -118,24 +148,30 @@ reactDom.render(
);
```
-result:
- 
+result:
+ 
+Example of a customization using only CSS: [here](https://github.com/InseeFrLab/onyxia-ui/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/components/KcApp.tsx)
+(the [index.tsx](https://github.com/InseeFrLab/onyxia-ui/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/index.tsx#L89-L94) )
+and the result you can expect:
+
+//TODO
### Changing the look **and** feel
-If you want to really re-implement the pages the best approach is to
-create you own version of the [``](https://github.com/garronej/keycloakify/blob/develop/src/lib/components/KcApp.tsx).
+If you want to really re-implement the pages, the best approach is to
+create your own version of the [``](https://github.com/garronej/keycloakify/blob/develop/src/lib/components/KcApp.tsx).
Copy/past some of [the components](https://github.com/garronej/keycloakify/tree/develop/src/lib/components) provided by this module and start hacking around.
-You can find an example of a fancy customization [here](https://github.com/InseeFrLab/onyxia-ui/tree/master/src/app/components/KcApp).
+You can find an example of such customization [here](https://github.com/InseeFrLab/onyxia-ui/tree/master/src/app/components/KcApp).
+
+And you can test the result in production by trying the login register page of [Onyxia](https://datalab.sspcloud.fr)
+
### Hot reload
-By default, in order to see your changes you will have to wait for
-`yarn build` to complete which can takes sevrall minute.
-
+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, in [storybook](https://storybook.js.org/)
for example you can use `kcContextMocks`.
@@ -147,7 +183,6 @@ import {
} from "keycloakify";
reactDom.render(
- kcContext !== undefined ?