Update changelog v0.3.10

CHANGELOG.md

@@ -1,3 +1,53 @@
+### **0.3.10** (2021-03-26)  
+  
+- Handle <style> tag, improve documentation    
+  
+### **0.3.9** (2021-03-25)  
+  
+- Update readme  
+- Document  --external-assets  
+- Update README.md  
+- Update README.md  
+- Update README.md    
+  
+### **0.3.8** (2021-03-22)  
+  
+- Make standalone mode the default    
+  
+### **0.3.7** (2021-03-22)  
+  
+- (test) external asset mode by default    
+  
+### **0.3.6** (2021-03-22)  
+  
+- Fix previous release    
+  
+### **0.3.5** (2021-03-22)  
+  
+- support homepage with urlPath    
+  
+### **0.3.4** (2021-03-22)  
+  
+- Bugfix: Import assets from CSS    
+  
+### **0.3.3** (2021-03-22)  
+  
+- Fix submit not receving correct text    
+  
+### **0.3.2** (2021-03-21)  
+  
+- Fix broken previous release    
+  
+### **0.3.1** (2021-03-21)  
+  
+- kcHeaderClass can be updated after initial mount    
+  
+## **0.3.0** (2021-03-20)  
+  
+- Bump version  
+- Feat: Cary over states using URL search params  
+- Bugfix: with kcHtmlClass    
+  
 ### **0.2.10** (2021-03-19)  
   
 - Remove dependency to denoify    

README.md

@@ -20,8 +20,10 @@
 
 The problem: 
 
-![keycloak_before](https://user-images.githubusercontent.com/6702424/108838381-dbbbcf80-75d3-11eb-8ae8-db41563ef9db.gif)
-
+<p align="center">
+    <i>Without keycloakify:</i><br>
+    <img src="https://user-images.githubusercontent.com/6702424/108838381-dbbbcf80-75d3-11eb-8ae8-db41563ef9db.gif">
+</p>
 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.  
@@ -29,42 +31,39 @@ to reproduce the look and feel of a specific app. Not mentioning the maintenance
 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 🍸
 
-TODO: Insert video after.
+<p align="center">
+    <i>With keycloakify:</i><br>
+    <img src="https://github.com/InseeFrLab/keycloakify/releases/download/v0.3.8/keycloakify_after.gif">
+</p>
 
-Tested with the following Keycloak versions: 
-- [11.0.3](https://hub.docker.com/layers/jboss/keycloak/11.0.3/images/sha256-4438f1e51c1369371cb807dffa526e1208086b3ebb9cab009830a178de949782?context=explore)  
-- [12.0.4](https://hub.docker.com/layers/jboss/keycloak/12.0.4/images/sha256-67e0c88e69bd0c7aef972c40bdeb558a974013a28b3668ca790ed63a04d70584?context=explore)  
-
-**Disclaimer**: This tool will be maintained to stay compatible with Keycloak v11 and up, however, the default pages you will get 
-(before you customize it) will always be the ones of the Keycloak v11.
+**TL;DR**: [Here](https://github.com/garronej/keycloakify-demo-app) is a Hello World React project with Keycloakify set up.  
 
 - [Motivations](#motivations)
 - [How to use](#how-to-use)
   - [Setting up the build tool](#setting-up-the-build-tool)
+    - [Specify from where the resources should be downloaded.](#specify-from-where-the-resources-should-be-downloaded)
   - [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 the look **and** feel](#changing-the-look-and-feel)
     - [Hot reload](#hot-reload)
-- [How to implement context persistance](#how-to-implement-context-persistance)
-  - [If your keycloak is a subdomain of your app.](#if-your-keycloak-is-a-subdomain-of-your-app)
-  - [Else](#else)
 - [GitHub Actions](#github-actions)
-- [REQUIREMENTS](#requirements)
+- [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)
+- [Implement context persistence (optional)](#implement-context-persistence-optional)
 - [API Reference](#api-reference)
   - [The build tool](#the-build-tool)
-  - [The fronted lib ( imported into your react app )](#the-fronted-lib--imported-into-your-react-app-)
 
 # How to use
 ## Setting up the build tool
 
-Add `keycloakify` to the dev dependencies of your project `npm install --save-dev keycloakify` or `yarn add --dev keycloakify`
-then configure your `package.json` build's script to build the keycloak's theme by adding `&& build-keycloak-theme`.
-
-Typically you will get: 
-
-`package.json`
+[`package.json`](https://github.com/garronej/keycloakify-demo-app/blob/main/package.json)
 ```json
-"devDependencies": {
+"homepage": "https://URL.OF/YOUR-APP"
+"dependencies": {
     "keycloakify": "^0.0.10"
 },
 "scripts": {
@@ -72,14 +71,60 @@ Typically you will get:
 },
 ```
 
-Then run `yarn keycloak` or `npm run keycloak`, you will be provided with instructions
-about how to load the theme into Keycloak.
+It is mandatory that you specify the url where your app will be available
+using the `homepage` field.
+
+Once you've edited your `package.json` you can install your new
+dependency with `yarn install` and build the keycloak theme with
+`yarn keycloak`. 
+
+Once the build is complete instructions about how to load
+the theme into Keycloak are printed in the console.
+
+### Specify from where the resources should be downloaded.
+
+*TL;DR*: Building the theme with the `--external-assets` option enables the login
+page to load faster for first time users but it also implies that:  
+- If the app is down, your Keycloak login and register pages are down as well.
+- Each time the app is updated, the theme must be updated as well.
+- CORS must be enabled for fonts.
+
+<details>
+  <summary>Click to expand</summary>
+
+When you run `npx build-keycloak-theme` without arguments, Keycloakify will build
+a standalone version of the Keycloak theme. That is to say even if your app, the
+one hosted at the url specified as `homepage`, is down the Keycloak theme will still work.  
+It also mean that you won't have to update your theme on your Keycloak server each time 
+your app is updated.  
+In this mode, the default, every asset are served by the keycloak server. 
+The drawback of this approach is that when users access the login page for the first time 
+they have to download the whole app again. 
+You probably have [long-term asset caching](https://create-react-app.dev/docs/production-build/#static-file-caching)
+enabled in the server that host your app ([example](https://github.com/garronej/keycloakify-demo-app/blob/224c43383548635a463fa68e8909c147ac189f0e/nginx.conf#L14)) 
+so it can be interesting to only serve the html from Keycloak server and everything
+else, your JS bundles, your CSS ect from the server that host your app.  
+
+To enable this behavior you car run:
+```bash
+npx build-keycloak-theme --external-assets
+```
+(instead of `npx build-keycloak-theme`)
+
+This is something you probably want to do in your CI pipeline. [Example](https://github.com/garronej/keycloakify-demo-app/blob/224c43383548635a463fa68e8909c147ac189f0e/.github/workflows/ci.yaml#L112)
+
+Also note that there is [a same-origin policy exception for fonts](https://en.wikipedia.org/wiki/Same-origin_policy#cite_note-3) so you must enabled
+CORS for fonts on the server hosting your app. Concretely this mean that your server should add a `Access-Control-Allow-Origin: *` response header to 
+GET request on *.woff2?. [Example with Nginx](https://github.com/garronej/keycloakify-demo-app/blob/224c43383548635a463fa68e8909c147ac189f0e/nginx.conf#L18-L20)
+
+</details>
+
 
 ## Developing your login and register pages in your React app
 
 ### Just changing the look
 
-The fist approach is to only arr/replace the default class names by your
+The first approach is to only arr/replace the default class names by your
 own.
 
 ```tsx
@@ -154,25 +199,6 @@ Checkout [this concrete example](https://github.com/garronej/keycloakify-demo-ap
 
 *NOTE: keycloak-react-theming was renamed keycloakify since this video was recorded*
 [![kickstart_video](https://user-images.githubusercontent.com/6702424/108877866-f146ee80-75ff-11eb-8120-003b3c5f6dd8.png)](https://youtu.be/xTz0Rj7i2v8)
-# How to implement context persistance
-
-If you want dark mode preference, language and others users preferences 
-to persist within the page served by keycloak here are the methods you can
-adopt.
-
-## If your keycloak is a subdomain of your app.
-
-E.g: Your app url is `my-app.com` and your keycloak url is `auth.my-app.com`.
-
-In this case there is a very straightforward approach and it is to use [`powerhooks/useGlobalState`](https://github.com/garronej/powerhooks).
-Instead of `{ "persistance": "localStorage" }` use `{ "persistance": "cookie" }`.
-
-## Else
-
-You will have to use URL parameters to passes states when you redirect to 
-the login page.
-
-TOTO: Provide a clean way, as abstracted as possible, way to do that.
 
 # GitHub Actions
 
@@ -181,32 +207,115 @@ TOTO: Provide a clean way, as abstracted as possible, way to do that.
 [Here is a demo repo](https://github.com/garronej/keycloakify-demo-app) to show how to automate
 the building and publishing of the theme (the .jar file).
 
-# REQUIREMENTS
+# Requirements 
+
+Tested with the following Keycloak versions: 
+- [11.0.3](https://hub.docker.com/layers/jboss/keycloak/11.0.3/images/sha256-4438f1e51c1369371cb807dffa526e1208086b3ebb9cab009830a178de949782?context=explore)  
+- [12.0.4](https://hub.docker.com/layers/jboss/keycloak/12.0.4/images/sha256-67e0c88e69bd0c7aef972c40bdeb558a974013a28b3668ca790ed63a04d70584?context=explore)  
+
+This tool will be maintained to stay compatible with Keycloak v11 and up, however, the default pages you will get 
+(before you customize it) will always be the ones of the Keycloak v11.
 
 This tools assumes you are bundling your app with Webpack (tested with 4.44.2) .
 It assumes there is a `build/` directory at the root of your react project directory containing a `index.html` file
-and a `static/` directory generated by webpack.
+and a `build/static/` directory generated by webpack.
 
 **All this is defaults with [`create-react-app`](https://create-react-app.dev)** (tested with 4.0.3=)
 
 - For building the theme: `mvn` (Maven) must be installed
-- For development, (testing the theme in a local container ): `rm`, `mkdir`, `wget`, `unzip` are assumed to be available
+- For development (testing the theme in a local container ): `rm`, `mkdir`, `wget`, `unzip` are assumed to be available
   and `docker` up and running.
 
 NOTE: This build tool has only be tested on MacOS.
 
+# Limitations
+
+## `process.env.PUBLIC_URL` not supported.
+
+You won't be able to [import things from your public directory in your JavaScript code](https://create-react-app.dev/docs/using-the-public-folder/#adding-assets-outside-of-the-module-system). (This isn't recommended anyway).
+
+## `@font-face` importing fonts from the `src/` dir
+
+**If you are building the theme with `--external-assets` this limitation doesn't apply.**  
+### Example of setup that **won't** work 
+
+- We have a `fonts/` directory in `src/`
+- We import the font like this [`src: url("/fonts/my-font.woff2") format("woff2");`(https://github.com/garronej/keycloakify-demo-app/blob/07d54a3012ef354ee12b1374c6f7ad1cb125d56b/src/fonts.scss#L4) in a `.scss` a file.  
+
+### Workarounds  
+
+If it is possible, use Google Fonts or any other font provider.
+
+If you want to host your font recommended approach is to move your fonts into the `public` 
+directory and to place your `@font-face` statements in the `public/index.html`.  
+Example [here]().  
+
+You can also [use your explicit url](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/src/fonts.scss#L16) but don't forget [`Access-Control-Allow-Origin`](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/nginx.conf#L17-L19).
+
+# Implement context persistence (optional)
+
+If, before logging in, a user has selected a specific language 
+you don't want it to be reset to default when the user gets redirected to
+the login or register pages.  
+  
+Same goes for the dark mode, you don't want, if the user had it enabled
+to show the login page with light themes.  
+  
+The problem is that you are probably using `localStorage` to persist theses values across
+reload but, as the Keycloak pages are not served on the same domain that the rest of your
+app you won't be able to carry over states using `localStorage`.  
+
+The only reliable solution is to inject parameters into the URL before
+redirecting to Keycloak. We integrate with 
+[`keycloak-js`](https://github.com/keycloak/keycloak-documentation/blob/master/securing_apps/topics/oidc/javascript-adapter.adoc), 
+by providing you a way to tell `keycloak-js` that you would like to inject
+some search parameters before redirecting.  
+
+The method also works with [`@react-keycloak/web`](https://www.npmjs.com/package/@react-keycloak/web) (use the `initOptions`).
+
+You can implement your own mechanism to pass the states in the URL and
+restore it on the other side but we recommend using `powerhooks/useGlobalState`
+from the library [`powerhooks`](https://www.powerhooks.dev) that provide an elegant
+way to handle states such as `isDarkModeEnabled` or `selectedLanguage`.
+
+Let's modify [the example](https://github.com/keycloak/keycloak-documentation/blob/master/securing_apps/topics/oidc/javascript-adapter.adoc) from the official `keycloak-js` documentation to
+enables the states of `useGlobalStates` to be injected in the URL before redirecting.  
+Note that the states are automatically restored on the other side by `powerhooks`
+
+```typescript
+import keycloak_js from "keycloak-js";
+import { injectGlobalStatesInSearchParams } from "powerhooks/useGlobalState";
+import { createKeycloakAdapter } from "keycloakify";
+
+//...
+
+const keycloakInstance = keycloak_js({
+    "url": "http://keycloak-server/auth",
+    "realm": "myrealm",
+    "clientId": "myapp"
+});
+
+keycloakInstance.init({
+    "onLoad": 'check-sso',
+    "silentCheckSsoRedirectUri": window.location.origin + "/silent-check-sso.html",
+    "adapter": createKeycloakAdapter({
+        "transformUrlBeforeRedirect": injectGlobalStatesInSearchParams,
+        keycloakInstance
+    })
+});
+
+//...
+```
+
+If you really want to go the extra miles and avoid having the white
+flash of the blank html before the js bundle have been evaluated
+[here is a snippet](https://github.com/InseeFrLab/onyxia-ui/blob/a77eb502870cfe6878edd0d956c646d28746d053/public/index.html#L5-L54) that you can place in your `public/index.html` if you are using `powerhooks/useGlobalState`.
+
 # API Reference 
 
 ## The build tool 
 
 Part of the lib that runs with node, at build time.
 
-- `npx build-keycloak-theme`: Builds the theme, the CWD is assumed to be the root of your react project.
-- `npx download-sample-keycloak-themes`: Downloads the keycloak default themes (for development purposes)
-
-## The fronted lib ( imported into your react app )
-
-Part of the lib that you import in your react project and runs on the browser.
-
-**TODO**
-
+- `npx build-keycloak-theme [--external-assets]`: Builds the theme, the CWD is assumed to be the root of your react project.
+- `npx download-sample-keycloak-themes`: Downloads the keycloak default themes (for development purposes)

package.json

@@ -1,6 +1,6 @@
 {
     "name": "keycloakify",
-    "version": "0.2.10",
+    "version": "0.3.10",
     "description": "Keycloak theme generator for Reacts app",
     "repository": {
         "type": "git",

src/bin/build-keycloak-theme/generateFtl/index.ts

@@ -2,7 +2,8 @@
 
 import cheerio from "cheerio";
 import {
-    replaceImportFromStaticInJsCode,
+    replaceImportsFromStaticInJsCode,
+    replaceImportsInInlineCssCode,
     generateCssCodeToDefineGlobals
 } from "../replaceImportFromStatic";
 import fs from "fs";
@@ -11,9 +12,9 @@ import { objectKeys } from "evt/tools/typeSafety/objectKeys";
 
 export const pageIds = ["login.ftl", "register.ftl", "info.ftl", "error.ftl", "login-reset-password.ftl", "login-verify-email.ftl"] as const;
 
-export type PageId =  typeof pageIds[number];
+export type PageId = typeof pageIds[number];
 
-function loadAdjacentFile(fileBasename: string){
+function loadAdjacentFile(fileBasename: string) {
     return fs.readFileSync(pathJoin(__dirname, fileBasename))
         .toString("utf8");
 };
@@ -29,29 +30,51 @@ function loadFtlFile(ftlFileBasename: PageId | "template.ftl") {
     }
 }
 
+export type Mode = {
+    type: "standalone";
+    urlPathname: string;
+} | {
+    type: "external assets";
+    urlPathname: string;
+    urlOrigin: string;
+}
+
 export function generateFtlFilesCodeFactory(
     params: {
         ftlValuesGlobalName: string;
         cssGlobalsToDefine: Record<string, string>;
         indexHtmlCode: string;
+        mode: Mode;
     }
 ) {
 
-    const { ftlValuesGlobalName, cssGlobalsToDefine, indexHtmlCode } = params;
+    const { ftlValuesGlobalName, cssGlobalsToDefine, indexHtmlCode, mode } = params;
 
     const $ = cheerio.load(indexHtmlCode);
 
     $("script:not([src])").each((...[, element]) => {
 
-        const { fixedJsCode } = replaceImportFromStaticInJsCode({
+        const { fixedJsCode } = replaceImportsFromStaticInJsCode({
             ftlValuesGlobalName,
-            "jsCode": $(element).html()!
+            "jsCode": $(element).html()!,
+            mode
         });
 
         $(element).text(fixedJsCode);
 
     });
 
+    $("style").each((...[, element]) => {
+
+        const { fixedCssCode } = replaceImportsInInlineCssCode({
+            "cssCode": $(element).html()!,
+            mode
+        });
+
+        $(element).text(fixedCssCode);
+
+    });
+
     ([
         ["link", "href"],
         ["script", "src"],
@@ -60,11 +83,28 @@ export function generateFtlFilesCodeFactory(
 
             const href = $(element).attr(attrName);
 
-            if (!href?.startsWith("/")) {
+            if (href === undefined) {
                 return;
             }
 
-            $(element).attr(attrName, "${url.resourcesPath}/build" + href);
+            switch (mode.type) {
+                case "external assets":
+                    $(element).attr(
+                        attrName,
+                        href.replace(/^\//, `${mode.urlOrigin}/`)
+                    );
+                    break;
+                case "standalone":
+                    $(element).attr(
+                        attrName,
+                        href.replace(
+                            new RegExp(`^${mode.urlPathname.replace(/\//g, "\\/")}`),
+                            "${url.resourcesPath}/build/"
+                        )
+                    );
+                    break;
+            }
+
 
         })
     );
@@ -89,9 +129,10 @@ export function generateFtlFilesCodeFactory(
             ...(Object.keys(cssGlobalsToDefine).length === 0 ? [] : [
                 '',
                 '<style>',
-                generateCssCodeToDefineGlobals(
-                    { cssGlobalsToDefine }
-                ).cssCodeToPrependInHead,
+                generateCssCodeToDefineGlobals({
+                    cssGlobalsToDefine,
+                    "urlPathname": mode.urlPathname
+                }).cssCodeToPrependInHead,
                 '</style>',
                 ''
             ]),

src/bin/build-keycloak-theme/generateKeycloakThemeResources.ts

@@ -3,26 +3,28 @@ import { transformCodebase } from "../tools/transformCodebase";
 import * as fs from "fs";
 import { join as pathJoin } from "path";
 import {
-    replaceImportFromStaticInCssCode,
-    replaceImportFromStaticInJsCode
+    replaceImportsInCssCode,
+    replaceImportsFromStaticInJsCode
 } from "./replaceImportFromStatic";
-import { generateFtlFilesCodeFactory, pageIds } from "./generateFtl";
-import { builtinThemesUrl } from "../install-builtin-keycloak-themes";
-import { downloadAndUnzip } from "../tools/downloadAndUnzip";
+import { generateFtlFilesCodeFactory, pageIds, Mode } from "./generateFtl";
+import { builtinThemesUrl } from "../install-builtin-keycloak-themes";
+import { downloadAndUnzip } from "../tools/downloadAndUnzip";
 import * as child_process from "child_process";
-import { ftlValuesGlobalName } from "./ftlValuesGlobalName";
-import { resourcesCommonPath, resourcesPath, subDirOfPublicDirBasename } from "../../lib/kcContextMocks/urlResourcesPath";
-import { isInside } from "../tools/isInside";
+import { ftlValuesGlobalName } from "./ftlValuesGlobalName";
+import { resourcesCommonPath, resourcesPath, subDirOfPublicDirBasename } from "../../lib/kcContextMocks/urlResourcesPath";
+import { isInside } from "../tools/isInside";
+
 
 export function generateKeycloakThemeResources(
     params: {
         themeName: string;
         reactAppBuildDirPath: string;
         keycloakThemeBuildingDirPath: string;
+        mode: Mode;
     }
 ) {
 
-    const { themeName, reactAppBuildDirPath, keycloakThemeBuildingDirPath } = params;
+    const { themeName, reactAppBuildDirPath, keycloakThemeBuildingDirPath, mode } = params;
 
     const themeDirPath = pathJoin(keycloakThemeBuildingDirPath, "src", "main", "resources", "theme", themeName, "login");
 
@@ -43,30 +45,34 @@ export function generateKeycloakThemeResources(
                 return undefined;
             }
 
+            if (mode.type === "standalone") {
 
-            if (/\.css?$/i.test(filePath)) {
+                if (/\.css?$/i.test(filePath)) {
 
-                const { cssGlobalsToDefine, fixedCssCode } = replaceImportFromStaticInCssCode(
-                    { "cssCode": sourceCode.toString("utf8") }
-                );
+                    const { cssGlobalsToDefine, fixedCssCode } = replaceImportsInCssCode(
+                        { "cssCode": sourceCode.toString("utf8") }
+                    );
 
-                allCssGlobalsToDefine = {
-                    ...allCssGlobalsToDefine,
-                    ...cssGlobalsToDefine
-                };
+                    allCssGlobalsToDefine = {
+                        ...allCssGlobalsToDefine,
+                        ...cssGlobalsToDefine
+                    };
 
-                return { "modifiedSourceCode": Buffer.from(fixedCssCode, "utf8") };
+                    return { "modifiedSourceCode": Buffer.from(fixedCssCode, "utf8") };
 
-            }
+                }
 
-            if (/\.js?$/i.test(filePath)) {
+                if (/\.js?$/i.test(filePath)) {
 
-                const { fixedJsCode } = replaceImportFromStaticInJsCode({
-                    "jsCode": sourceCode.toString("utf8"),
-                    ftlValuesGlobalName
-                });
+                    const { fixedJsCode } = replaceImportsFromStaticInJsCode({
+                        "jsCode": sourceCode.toString("utf8"),
+                        ftlValuesGlobalName,
+                        mode
+                    });
 
-                return { "modifiedSourceCode": Buffer.from(fixedJsCode, "utf8") };
+                    return { "modifiedSourceCode": Buffer.from(fixedJsCode, "utf8") };
+
+                }
 
             }
 
@@ -80,7 +86,8 @@ export function generateKeycloakThemeResources(
         ftlValuesGlobalName,
         "indexHtmlCode": fs.readFileSync(
             pathJoin(reactAppBuildDirPath, "index.html")
-        ).toString("utf8")
+        ).toString("utf8"),
+        mode
     });
 
     pageIds.forEach(pageId => {

src/bin/build-keycloak-theme/index.ts

@@ -6,10 +6,13 @@ import type { ParsedPackageJson } from "./generateJavaStackFiles";
 import { join as pathJoin, relative as pathRelative, basename as pathBasename } from "path";
 import * as child_process from "child_process";
 import { generateDebugFiles, containerLaunchScriptBasename } from "./generateDebugFiles";
+import { URL } from "url";
 
 
 const reactProjectDirPath = process.cwd();
 
+const doUseExternalAssets = process.argv[2]?.toLowerCase() === "--external-assets";
+
 const parsedPackageJson: ParsedPackageJson = require(pathJoin(reactProjectDirPath, "package.json"));
 
 export const keycloakThemeBuildingDirPath = pathJoin(reactProjectDirPath, "build_keycloak");
@@ -22,7 +25,51 @@ if (require.main === module) {
     generateKeycloakThemeResources({
         keycloakThemeBuildingDirPath,
         "reactAppBuildDirPath": pathJoin(reactProjectDirPath, "build"),
-        "themeName": parsedPackageJson.name
+        "themeName": parsedPackageJson.name,
+        "mode": (() => {
+
+
+            const url = (() => {
+
+                const { homepage } = parsedPackageJson;
+
+                return homepage === undefined ?
+                    undefined :
+                    new URL(homepage);
+
+            })();
+
+            const urlPathname =
+                url === undefined ?
+                    "/" :
+                    url.pathname.replace(/([^/])$/, "$1/");
+
+
+
+            return !doUseExternalAssets ?
+                {
+                    "type": "standalone",
+                    urlPathname
+                } as const
+                :
+                {
+                    "type": "external assets",
+                    urlPathname,
+                    "urlOrigin": (() => {
+
+                        if (url === undefined) {
+                            console.error("ERROR: You must specify 'homepage' in your package.json");
+                            process.exit(-1);
+                        }
+
+                        return url.origin;
+
+                    })()
+
+                } as const;
+
+        })()
+
     });
 
     const { jarFilePath } = generateJavaStackFiles({

src/bin/build-keycloak-theme/replaceImportFromStatic.ts

@@ -1,25 +1,66 @@
 
 import * as crypto from "crypto";
 
-export function replaceImportFromStaticInJsCode(
+type Mode = {
+    type: "standalone";
+} | {
+    type: "external assets";
+    urlOrigin: string;
+    urlPathname: string;
+}
+
+export function replaceImportsFromStaticInJsCode(
     params: {
         ftlValuesGlobalName: string;
         jsCode: string;
+        mode: Mode;
     }
 ): { fixedJsCode: string; } {
 
-    const { jsCode, ftlValuesGlobalName } = params;
+    const { jsCode, ftlValuesGlobalName, mode } = params;
 
-    const fixedJsCode = jsCode!.replace(
-        /"static\//g,
-        `window.${ftlValuesGlobalName}.url.resourcesPath.replace(/^\\//,"") + "/build/static/`
+    const fixedJsCode = jsCode.replace(
+        /[a-z]+\.[a-z]+\+"static\//g,
+        (() => {
+            switch (mode.type) {
+                case "standalone":
+                    return `window.${ftlValuesGlobalName}.url.resourcesPath + "/build/static/`;
+                case "external assets":
+                    return `"${mode.urlOrigin}${mode.urlPathname}static/`;
+            }
+        })()
     );
 
     return { fixedJsCode };
 
 }
 
-export function replaceImportFromStaticInCssCode(
+export function replaceImportsInInlineCssCode(
+    params: {
+        cssCode: string;
+        mode: Mode;
+    }
+): { fixedCssCode: string; } {
+
+    const { cssCode, mode } = params;
+
+    const fixedCssCode = cssCode.replace(
+        /url\((\/[^/][^)]+)\)/g,
+        (...[,group])=> `url(${
+            (()=>{
+                switch(mode.type){
+                    case "standalone": return "${url.resourcesPath}/build" + group;
+                    case "external assets": return mode.urlOrigin + group
+                }
+            })()
+        })`
+    );
+
+    return { fixedCssCode };
+
+}
+
+export function replaceImportsInCssCode(
     params: {
         cssCode: string;
     }
@@ -32,7 +73,7 @@ export function replaceImportFromStaticInCssCode(
 
     const cssGlobalsToDefine: Record<string, string> = {};
 
-    new Set(cssCode.match(/(url\(\/[^)]+\))/g) ?? [])
+    new Set(cssCode.match(/url\(\/[^/][^)]+\)[^;}]*/g) ?? [])
         .forEach(match =>
             cssGlobalsToDefine[
             "url" + crypto
@@ -60,12 +101,13 @@ export function replaceImportFromStaticInCssCode(
 export function generateCssCodeToDefineGlobals(
     params: {
         cssGlobalsToDefine: Record<string, string>;
+        urlPathname: string;
     }
 ): {
     cssCodeToPrependInHead: string;
 } {
 
-    const { cssGlobalsToDefine } = params;
+    const { cssGlobalsToDefine, urlPathname } = params;
 
     return {
         "cssCodeToPrependInHead": [
@@ -73,12 +115,8 @@ export function generateCssCodeToDefineGlobals(
             ...Object.keys(cssGlobalsToDefine)
                 .map(cssVariableName => [
                     `--${cssVariableName}:`,
-                    [
-                        "url(",
-                        "${url.resourcesPath}/build" +
-                        cssGlobalsToDefine[cssVariableName].match(/^url\(([^)]+)\)$/)![1],
-                        ")"
-                    ].join("")
+                    cssGlobalsToDefine[cssVariableName]
+                        .replace(new RegExp(`url\\(${urlPathname.replace(/\//g, "\\/")}`, "g"), "url(${url.resourcesPath}/build/")
                 ].join(" "))
                 .map(line => `    ${line};`),
             "}"

src/lib/components/LoginResetPassword.tsx

@@ -66,7 +66,7 @@ export const LoginResetPassword = memo(({ kcContext, ...props }: { kcContext: Kc
                                     props.kcButtonBlockClass, props.kcButtonLargeClass
                                 )}
                                 type="submit"
-                                defaultValue={msgStr("doSubmit")}
+                                value={msgStr("doSubmit")}
                             />
                         </div>
                     </div>

src/lib/components/Register.tsx

@@ -113,7 +113,7 @@ export const Register = memo(({ kcContext, ...props }: { kcContext: KcContext.Re
 
                         <div id="kc-form-buttons" className={cx(props.kcFormButtonsClass)}>
                             <input className={cx(props.kcButtonClass, props.kcButtonPrimaryClass, props.kcButtonBlockClass, props.kcButtonLargeClass)} type="submit"
-                                defaultValue={msgStr("doRegister")} />
+                                value={msgStr("doRegister")} />
                         </div>
                     </div>
                 </form >

src/lib/components/Template.tsx

@@ -25,8 +25,7 @@ export type TemplateProps = {
     showUsernameNode?: ReactNode;
     formNode: ReactNode;
     infoNode?: ReactNode;
-} & { kcContext: KcContext.Template; }  & KcTemplateProps;
-
+} & { kcContext: KcContext.Template; } & KcTemplateProps;
 
 export const Template = memo((props: TemplateProps) => {
 
@@ -60,34 +59,35 @@ export const Template = memo((props: TemplateProps) => {
     );
 
     const {
-        realm, locale, auth, 
+        realm, locale, auth,
         url, message, isAppInitiatedAction
-    }= kcContext;
+    } = kcContext;
 
-    useEffect(()=>{
+    useEffect(() => {
 
-        if( !realm.internationalizationEnabled ){
+        if (!realm.internationalizationEnabled) {
             return;
         }
 
-        assert( locale !== undefined );
+        assert(locale !== undefined);
 
-        if( kcLanguageTag === getBestMatchAmongKcLanguageTag(locale.current) ){
+        if (kcLanguageTag === getBestMatchAmongKcLanguageTag(locale.current)) {
             return;
         }
 
-        window.location.href = 
+        window.location.href =
             locale.supported.find(({ languageTag }) => languageTag === kcLanguageTag)!.url;
 
-    },[kcLanguageTag]);
+    }, [kcLanguageTag]);
 
     const [isExtraCssLoaded, setExtraCssLoaded] = useReducer(() => true, false);
 
     useEffect(() => {
 
         let isUnmounted = false;
+        const cleanups: (() => void)[] = [];
 
-        const toArr = (x: string | readonly string[] | undefined) => 
+        const toArr = (x: string | readonly string[] | undefined) =>
             typeof x === "string" ? x.split(" ") : x ?? [];
 
         Promise.all(
@@ -114,13 +114,29 @@ export const Template = memo((props: TemplateProps) => {
             })
         );
 
-        document.getElementsByTagName("html")[0]
-            .classList
-            .add(cx(props.kcHtmlClass));
+        if (props.kcHtmlClass !== undefined) {
 
-        return () => { isUnmounted = true; };
+            const htmlClassList =
+                document.getElementsByTagName("html")[0]
+                    .classList;
 
-    }, []);
+            const tokens = cx(props.kcHtmlClass).split(" ")
+
+            htmlClassList.add(...tokens);
+
+            cleanups.push(() => htmlClassList.remove(...tokens));
+
+        }
+
+        return () => {
+
+            isUnmounted = true;
+
+            cleanups.forEach(f => f());
+
+        };
+
+    }, [props.kcHtmlClass]);
 
     if (!isExtraCssLoaded) {
         return null;
@@ -152,7 +168,7 @@ export const Template = memo((props: TemplateProps) => {
                                     <ul>
                                         {
                                             locale.supported.map(
-                                                ({ languageTag  }) =>
+                                                ({ languageTag }) =>
                                                     <li key={languageTag} className="kc-dropdown-item">
                                                         <a href="#" onClick={onChangeLanguageClickFactory(languageTag)}>
                                                             {getKcLanguageTagLabel(languageTag)}
@@ -218,21 +234,21 @@ export const Template = memo((props: TemplateProps) => {
                                         </div>
                                     </div>
                                 ) : (
-                                        <>
-                                            {showUsernameNode}
-                                            <div className={cx(props.kcFormGroupClass)}>
-                                                <div id="kc-username">
-                                                    <label id="kc-attempted-username">{auth?.attemptedUsername}</label>
-                                                    <a id="reset-login" href={url.loginRestartFlowUrl}>
-                                                        <div className="kc-login-tooltip">
-                                                            <i className={cx(props.kcResetFlowIcon)}></i>
-                                                            <span className="kc-tooltip-text">{msg("restartLoginTooltip")}</span>
-                                                        </div>
-                                                    </a>
-                                                </div>
+                                    <>
+                                        {showUsernameNode}
+                                        <div className={cx(props.kcFormGroupClass)}>
+                                            <div id="kc-username">
+                                                <label id="kc-attempted-username">{auth?.attemptedUsername}</label>
+                                                <a id="reset-login" href={url.loginRestartFlowUrl}>
+                                                    <div className="kc-login-tooltip">
+                                                        <i className={cx(props.kcResetFlowIcon)}></i>
+                                                        <span className="kc-tooltip-text">{msg("restartLoginTooltip")}</span>
+                                                    </div>
+                                                </a>
                                             </div>
-                                        </>
-                                    )
+                                        </div>
+                                    </>
+                                )
                             )
                     }
                 </header>

src/lib/index.ts

@@ -12,6 +12,7 @@ export * from "./components/Info";
 export * from "./components/Error";
 export * from "./components/LoginResetPassword";
 export * from "./components/LoginVerifyEmail";
+export * from "./keycloakJsAdapter";
 
 export * from "./tools/assert";
 

src/lib/keycloakJsAdapter.ts

@@ -0,0 +1,119 @@
+
+
+export declare namespace keycloak_js {
+
+    export type KeycloakPromiseCallback<T> = (result: T) => void;
+    export class KeycloakPromise<TSuccess, TError> extends Promise<TSuccess> {
+        success(callback: KeycloakPromiseCallback<TSuccess>): KeycloakPromise<TSuccess, TError>;
+        error(callback: KeycloakPromiseCallback<TError>): KeycloakPromise<TSuccess, TError>;
+    }
+    export interface KeycloakAdapter {
+        login(options?: KeycloakLoginOptions): KeycloakPromise<void, void>;
+        logout(options?: KeycloakLogoutOptions): KeycloakPromise<void, void>;
+        register(options?: KeycloakLoginOptions): KeycloakPromise<void, void>;
+        accountManagement(): KeycloakPromise<void, void>;
+        redirectUri(options: { redirectUri: string; }, encodeHash: boolean): string;
+    }
+    export interface KeycloakLogoutOptions {
+        redirectUri?: string;
+    }
+    export interface KeycloakLoginOptions {
+        scope?: string;
+        redirectUri?: string;
+        prompt?: 'none' | 'login';
+        action?: string;
+        maxAge?: number;
+        loginHint?: string;
+        idpHint?: string;
+        locale?: string;
+        cordovaOptions?: { [optionName: string]: string };
+    }
+
+    export type KeycloakInstance = Record<
+        "createLoginUrl" |
+        "createLogoutUrl" |
+        "createRegisterUrl",
+        (options: KeycloakLoginOptions | undefined) => string
+    > & {
+        createAccountUrl(): string;
+        redirectUri?: string;
+    }
+
+}
+
+/**
+* NOTE: This is just a slightly modified version of the default adapter in keycloak-js
+* The goal here is just to be able to inject search param in url before keycloak redirect.
+* Our use case for it is to pass over the login screen the states of useGlobalState
+* namely isDarkModeEnabled, lgn... 
+*/
+export function createKeycloakAdapter(
+    params: {
+        keycloakInstance: keycloak_js.KeycloakInstance;
+        transformUrlBeforeRedirect(url: string): string;
+    }
+): keycloak_js.KeycloakAdapter {
+
+    const { keycloakInstance, transformUrlBeforeRedirect } = params;
+
+    const neverResolvingPromise: keycloak_js.KeycloakPromise<void, void> = Object.defineProperties(
+        new Promise(() => { }),
+        {
+            "success": { "value": () => { } },
+            "error": { "value": () => { } }
+        }
+    );
+
+    return {
+        "login": options => {
+            window.location.replace(
+                transformUrlBeforeRedirect(
+                    keycloakInstance.createLoginUrl(
+                        options
+                    )
+                )
+            );
+            return neverResolvingPromise;
+        },
+        "logout": options => {
+            window.location.replace(
+                transformUrlBeforeRedirect(
+                    keycloakInstance.createLogoutUrl(
+                        options
+                    )
+                )
+            );
+            return neverResolvingPromise;
+        },
+        "register": options => {
+            window.location.replace(
+                transformUrlBeforeRedirect(
+                    keycloakInstance.createRegisterUrl(
+                        options
+                    )
+                )
+            );
+            return neverResolvingPromise;
+        },
+        "accountManagement": () => {
+            var accountUrl = transformUrlBeforeRedirect(keycloakInstance.createAccountUrl());
+            if (typeof accountUrl !== 'undefined') {
+                window.location.href = accountUrl;
+            } else {
+                throw new Error("Not supported by the OIDC server");
+            }
+            return neverResolvingPromise;
+        },
+        "redirectUri": options => {
+            if (options && options.redirectUri) {
+                return options.redirectUri;
+            } else if (keycloakInstance.redirectUri) {
+                return keycloakInstance.redirectUri;
+            } else {
+                return window.location.href;
+            }
+        }
+    };
+
+
+}

src/test/generateKeycloakThemeResources.ts

@@ -1,7 +1,7 @@
 
 import { join as pathJoin } from "path";
 import { generateKeycloakThemeResources } from "../bin/build-keycloak-theme/generateKeycloakThemeResources";
-import { 
+import {
     setupSampleReactProject,
     sampleReactProjectDirPath
 } from "./setupSampleReactProject";
@@ -9,8 +9,12 @@ import {
 setupSampleReactProject();
 
 generateKeycloakThemeResources({
-    "themeName": "onyxia-ui",
+    "themeName": "keycloakify-demo-app",
     "reactAppBuildDirPath": pathJoin(sampleReactProjectDirPath, "build"),
-    "keycloakThemeBuildingDirPath": pathJoin(sampleReactProjectDirPath, "build_keycloak_theme")
+    "keycloakThemeBuildingDirPath": pathJoin(sampleReactProjectDirPath, "build_keycloak_theme"),
+    "mode": {
+        "type": "standalone",
+        "urlPathname": "/keycloakify-demo-app/"
+    }
 });
 

src/test/replaceImportFromStatic.ts

@@ -1,11 +1,11 @@
 
 import { 
-    replaceImportFromStaticInJsCode,
-    replaceImportFromStaticInCssCode,
+    replaceImportsFromStaticInJsCode,
+    replaceImportsInCssCode,
     generateCssCodeToDefineGlobals
 } from "../bin/build-keycloak-theme/replaceImportFromStatic";
 
-const { fixedJsCode } = replaceImportFromStaticInJsCode({
+const { fixedJsCode } = replaceImportsFromStaticInJsCode({
     "ftlValuesGlobalName": "keycloakFtlValues",
     "jsCode": `
         function f() {
@@ -19,12 +19,13 @@ const { fixedJsCode } = replaceImportFromStaticInJsCode({
                 3: "0664cdc0"
             }[e] + ".chunk.js"
         }
-    `
+    `,
+    "mode": { "type": "standalone" }
 });
 
 console.log({ fixedJsCode });
 
-const { fixedCssCode, cssGlobalsToDefine } = replaceImportFromStaticInCssCode({
+const { fixedCssCode, cssGlobalsToDefine } = replaceImportsInCssCode({
     "cssCode": `
 
     .my-div {
@@ -45,6 +46,6 @@ const { fixedCssCode, cssGlobalsToDefine } = replaceImportFromStaticInCssCode({
 console.log({ fixedCssCode, cssGlobalsToDefine });
 
 
-const { cssCodeToPrependInHead } = generateCssCodeToDefineGlobals({ cssGlobalsToDefine });
+const { cssCodeToPrependInHead } = generateCssCodeToDefineGlobals({ cssGlobalsToDefine, "urlPathname": "/" });
 
 console.log({ cssCodeToPrependInHead });