Add documentation

README.md

@@ -2,7 +2,7 @@
     <img src="https://user-images.githubusercontent.com/6702424/80216211-00ef5280-863e-11ea-81de-59f3a3d4b8e4.png">  
 </p>
 <p align="center">
-    <i>Provides a way to customize Keycloak login and register pages with React</i>
+    <i>🔏 Keycloak theme generator for Reacts app💅</i>
     <br>
     <br>
     <img src="https://github.com/garronej/keycloak-react-theming/workflows/ci/badge.svg?branch=develop">
@@ -10,31 +10,87 @@
     <img src="https://img.shields.io/npm/dw/keycloak-react-theming">
     <img src="https://img.shields.io/npm/l/keycloak-react-theming">
 </p>
-<p align="center">
-  <a href="https://github.com/garronej/keycloak-react-theming">Home</a>
-  -
-  <a href="https://github.com/garronej/keycloak-react-theming">Documentation</a>
-</p>
 
-# REQUIREMENT
+# MOTIVATION
-## For building the theme: 
 
-- `mvn` must be installed
+The problem: 
 
-## For development, (testing the theme on a docker container ect ):
+![keycloak_before](https://user-images.githubusercontent.com/6702424/108838381-dbbbcf80-75d3-11eb-8ae8-db41563ef9db.gif)
 
-- `rm`
+When we redirected to Keycloak the user suffers from a harsh context switch.
-- `mkdir` )
+The language is set back to default and the theme is different, 
-- `wget`
-- `unzip`
 
-Tested on MacOS
+Keycloak does offer a way to customize the theme of theses pages but it will require a lot of raw HTML/CSS hacking
+to reproduce the look and feel of your app. Not mentioning the maintenance cost of such an endeavour.
 
-# USAGE
+Wouldn't it be great if we could just design the login and register pages as if they where part of our app while
+still letting Keycloak handle the heavy lifting of actually authenticating the users? 
 
-## Build the theme: 
+Here is `yarn add keycloak-react-theming` for you 🍸
-`npx build-keycloak-theme`
 
-## (Optional/Debug) Download more themes: 
+![image](https://user-images.githubusercontent.com/6702424/108833938-c9d72e00-75cd-11eb-8263-4334ca79275c.png)
+![image](https://user-images.githubusercontent.com/6702424/108834054-f68b4580-75cd-11eb-9661-b1a43836c4b0.png)
+![image](https://user-images.githubusercontent.com/6702424/108834220-32bea600-75ce-11eb-9e11-7661188beb7c.png)
 
-`npx download-sample-keycloak-themes`
+# How to use
+
+## Setting up the build tool
+
+Add `keycloak-react-theming` to the dev dependencies of your project `npm install --save-dev keycloak-react-theming` or `yarn add --dev keycloak-react-theming`
+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`:
+```json
+  "devDependencies": {
+    "keycloak-react-theming": "^0.0.10",
+    [...]
+  },
+  "scripts": {
+    "build": "react-scripts build && build-keycloak-theme",
+    [...]
+  },
+```
+
+Then build your app with `yarn run build` or `npm run build`, you will be provided with instructions
+about how to load the theme into Keycloak.
+
+## Developing your login and register pages in your React app
+
+TODO
+
+# How to implement context persistance
+
+If you want dark mode preference, language and others users preferences your can do so
+very easily by using [`powerhooks/useGlobalState`](https://github.com/garronej/powerhooks)
+
+WARNING: `powerhooks` is still a work in progress.
+
+# REQUIREMENTS
+
+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.
+
+**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.
+
+NOTE: This build tool has only be tested on MacOS.
+
+# 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 
+
+Part of the lib that you import in your react project and runs on the browser.
+
+**TODO**

package-lock.json

@@ -1,11 +1,11 @@
 {
     "name": "keycloak-react-theming",
-    "version": "0.0.10",
+    "version": "0.0.11",
     "lockfileVersion": 2,
     "requires": true,
     "packages": {
         "": {
-            "version": "0.0.10",
+            "version": "0.0.11",
             "license": "MIT",
             "dependencies": {
                 "cheerio": "^1.0.0-rc.5"

package.json

@@ -1,7 +1,7 @@
 {
     "name": "keycloak-react-theming",
-    "version": "0.0.10",
+    "version": "0.0.11",
-    "description": "Provides a way to customize Keycloak login and register pages with React",
+    "description": "Keycloak theme generator for Reacts app",
     "repository": {
         "type": "git",
         "url": "git://github.com/garronej/keycloak-react-theming.git"

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

@@ -2,6 +2,8 @@
 import * as fs from "fs";
 import { join as pathJoin, dirname as pathDirname, basename as pathBasename } from "path";
 
+export const containerLaunchScriptBasename = "start_keycloak_testing_container.sh";
+
 /** Files for being able to run a hot reload keycloak container */
 export function generateDebugFiles(
     params: {
@@ -34,7 +36,7 @@ export function generateDebugFiles(
     const containerName = "keycloak-testing-container";
 
     fs.writeFileSync(
-        pathJoin(keycloakThemeBuildingDirPath, "start_keycloak_testing_container.sh"),
+        pathJoin(keycloakThemeBuildingDirPath, containerLaunchScriptBasename),
         Buffer.from(
             [
                 "#!/bin/bash",

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

@@ -14,7 +14,7 @@ export function generateJavaStackFiles(
         parsedPackageJson: ParsedPackageJson;
         keycloakThemeBuildingDirPath: string;
     }
-): void {
+): { jarFilePath: string; } {
 
     const {
         parsedPackageJson: { name, version, homepage },
@@ -94,5 +94,7 @@ export function generateJavaStackFiles(
 
     }
 
+    return { "jarFilePath": pathJoin(keycloakThemeBuildingDirPath, "target", `${name}-${version}.jar`) };
+
 }
 

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

@@ -3,9 +3,10 @@
 import { generateKeycloakThemeResources } from "./generateKeycloakThemeResources";
 import { generateJavaStackFiles } from "./generateJavaStackFiles";
 import type { ParsedPackageJson } from "./generateJavaStackFiles";
-import { join as pathJoin } from "path";
+import { join as pathJoin, relative as pathRelative, basename as pathBasename } from "path";
 import * as child_process from "child_process";
-import { generateDebugFiles } from "./generateDebugFiles";
+import { generateDebugFiles, containerLaunchScriptBasename } from "./generateDebugFiles";
+
 
 const reactProjectDirPath = process.cwd();
 
@@ -13,6 +14,9 @@ const parsedPackageJson: ParsedPackageJson = require(pathJoin(reactProjectDirPat
 
 export const keycloakThemeBuildingDirPath = pathJoin(reactProjectDirPath, "build_keycloak");
 
+
+console.log("🔏 Building the keycloak theme...⌚");
+
 if (require.main === module) {
 
     generateKeycloakThemeResources({
@@ -21,7 +25,7 @@ if (require.main === module) {
         "themeName": parsedPackageJson.name
     });
 
-    generateJavaStackFiles({
+    const { jarFilePath } = generateJavaStackFiles({
         parsedPackageJson,
         keycloakThemeBuildingDirPath
     });
@@ -36,4 +40,36 @@ if (require.main === module) {
         "packageJsonName": parsedPackageJson.name
     });
 
+    console.log([
+        '',
+        `✅ Your keycloak theme has been generated and bundled into ./${pathRelative(reactProjectDirPath, jarFilePath)} 🚀`,
+        `It is to be placed in "/opt/jboss/keycloak/standalone/deployments" in the container running a jboss/keycloak Docker image. (Tested with 11.0.3)`,
+        '',
+        'Using Helm (https://github.com/codecentric/helm-charts), edit to reflect:',
+        '',
+        'value.yaml: ',
+        '    extraInitContainers: |',
+        '        - name: realm-ext-provider',
+        '          image: curlimages/curl',
+        '          imagePullPolicy: IfNotPresent',
+        '          command:',
+        '            - sh',
+        '          args:',
+        '            - -c',
+        `            - curl -L -f -S -o /extensions/${pathBasename(jarFilePath)} https://AN.URL.FOR/${pathBasename(jarFilePath)}`,
+        '          volumeMounts:',
+        '            - name: extensions',
+        '              mountPath: /extensions',
+        '        ',
+        '        extraVolumeMounts: |',
+        '            - name: extensions',
+        '              mountPath: /opt/jboss/keycloak/standalone/deployments',
+        '',
+        `To enable the theme within keycloak log into the admin console, go to your realm settings, click on the theme tab then select ${parsedPackageJson.name} `,
+        '',
+        'To test your theme locally you can spin up a Keycloak container image with the theme loaded by running:',
+        '',
+        `$ ./${pathRelative(reactProjectDirPath, pathJoin(keycloakThemeBuildingDirPath, containerLaunchScriptBasename))}`
+    ].join("\n"));
+
 }