From e85f25434fc161eb6cdab27b263c5424563c8bbd Mon Sep 17 00:00:00 2001
From: Erik Jan de Wit <erikjan.dewit@gmail.com>
Date: Fri, 16 Aug 2024 11:09:18 +0200
Subject: [PATCH] added documentation on how use npm packages (#31426)

Signed-off-by: Erik Jan de Wit <erikjan.dewit@gmail.com>
---
 .../server_development/topics.adoc            |  1 +
 .../topics/themes-react.adoc                  | 65 +++++++++++++++++++
 .../server_development/topics/themes.adoc     |  1 +
 3 files changed, 67 insertions(+)
 create mode 100644 docs/documentation/server_development/topics/themes-react.adoc

diff --git a/docs/documentation/server_development/topics.adoc b/docs/documentation/server_development/topics.adoc
index f97b0f6d94..d1a915fc80 100644
--- a/docs/documentation/server_development/topics.adoc
+++ b/docs/documentation/server_development/topics.adoc
@@ -1,6 +1,7 @@
 include::topics/preface.adoc[]
 include::topics/admin-rest-api.adoc[]
 include::topics/themes.adoc[]
+include::topics/themes-react.adoc[]
 include::topics/themes-selector.adoc[]
 include::topics/themes-resources.adoc[]
 include::topics/locale-selector.adoc[]
diff --git a/docs/documentation/server_development/topics/themes-react.adoc b/docs/documentation/server_development/topics/themes-react.adoc
new file mode 100644
index 0000000000..0e47332d48
--- /dev/null
+++ b/docs/documentation/server_development/topics/themes-react.adoc
@@ -0,0 +1,65 @@
+[[_theme_react]]
+== Themes based on React
+
+The admin console and account console are based on React.
+To fully customize these you can use the React based npm packages.
+There are two packages:
+
+* `@keycloak/keycloak-admin-ui`: This is the base theme for the admin console.
+* `@keycloak/keycloak-account-ui`: This is the base theme for the account console.
+
+Both packages are available on npm.
+
+=== Installing the packages
+
+To install the packages, run the following command:
+
+[source,bash]
+----
+pnpm install @keycloak/keycloak-account-ui
+----
+
+=== Using the packages
+
+To use these pages you'll need to add KeycloakProvider in your component hierarchy to setup what client, realm and url to use.
+
+[source,javascript]
+----
+import { KeycloakProvider } from "@keycloak/keycloak-ui-shared";
+
+//...
+
+<KeycloakProvider environment={{
+      serverBaseUrl: "http://localhost:8080",
+      realm: "master",
+      clientId: "security-admin-console"
+  }}>
+  {/* rest of you application */}
+</KeycloakProvider>
+----
+
+=== Translating the pages
+
+The pages are translated using the `i18next` library.
+You can set it up as described on their [website](https://react.i18next.com/).
+If you want to use the translations that are provided then you need to add i18next-http-backend to your project and add:
+
+[source,javascript]
+----
+backend: {
+  loadPath: `http://localhost:8080/resources/master/account/{lng}}`,
+  parse: (data: string) => {
+    const messages = JSON.parse(data);
+
+    const result: Record<string, string> = {};
+    messages.forEach((v) => (result[v.key] = v.value)); //need to convert to record
+    return result;
+  },
+},
+----
+
+=== Using the pages
+
+All "pages" are React components that can be used in your application.
+To see what components are available, see the [source](https://github.com/keycloak/keycloak/blob/main/js/apps/account-ui/src/index.ts).
+Or have a look at the [quick start](https://github.com/keycloak/keycloak-quickstarts/tree/main/extension/extend-admin-console-node) to see how to use them.
diff --git a/docs/documentation/server_development/topics/themes.adoc b/docs/documentation/server_development/topics/themes.adoc
index acce2c9202..0912864377 100644
--- a/docs/documentation/server_development/topics/themes.adoc
+++ b/docs/documentation/server_development/topics/themes.adoc
@@ -461,3 +461,4 @@ To deploy the archive to {project_name}, add it to the `providers/` directory of
 === Additional resources for Themes
 * For the inspiration, see <<_default-themes,Default Themes>> bundled inside {project_name}.
 * {quickstartRepo_link}[{quickstartRepo_name}] - Directory `extension` of the quickstarts repository contains some theme examples, which can be also used as an inspiration.
+