Keycloakify

https://docs.keycloakify.dev
Admin
Keycloakify is a tool for creating custom Keycloak themes using modern frontend technologies like...
Tokens:73,841
Snippets:590
Trust Score:7.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies with bun

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Install keycloakify and the shadcn login theme package using bun.

```bash
bun add keycloakify @oussemasahbeni/keycloakify-login-shadcn
```

--------------------------------

### Install and build commands for bun

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Runs bun install and then bun run build-keycloak-theme from the monorepo root.

```bash
bun install
bun run build-keycloak-theme
```

--------------------------------

### Install and build commands for npm

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Runs npm install and then npm run build-keycloak-theme from the monorepo root.

```bash
npm install
npm run build-keycloak-theme
```

--------------------------------

### Initialize keycloak-theme app from starter template

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Clones the keycloakify-starter repository into apps/keycloak-theme and removes the .git, .github, and yarn.lock files to start fresh.

```bash
cd my-monorepo
git clone https://github.com/keycloakify/keycloakify-starter apps/keycloak-theme
rm -rf apps/keycloak-theme/.git
rm -rf apps/keycloak-theme/.github
rm apps/keycloak-theme/yarn.lock
```

--------------------------------

### Install dependencies

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/nx

Installs the project dependencies using npm, pnpm, or yarn.

```bash
npm install # or `pnpm install` or `yarn`...
```

--------------------------------

### Install and build commands for pnpm

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Runs pnpm install and then pnpm run build-keycloak-theme from the monorepo root.

```bash
pnpm install
pnpm run build-keycloak-theme
```

--------------------------------

### Install Keycloakify with bun

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Installs keycloakify and optionally Storybook as dev dependencies using bun. Storybook installation is optional.

```bash
bun add keycloakify
# Installing storybook is optional
bun add --dev storybook @storybook/react @storybook/react-vite
```

--------------------------------

### Vite configuration with startKeycloakOptions

Source: https://docs.keycloakify.dev/features/compiler-options/startkeycloakoptions

Example of configuring startKeycloakOptions in vite.config.ts. All options are optional. The dockerImage option allows using an alternative Docker image or pinning a version. dockerExtraArgs passes extra arguments to the docker run command. keycloakExtraArgs starts Keycloak with extra arguments. extensionJars loads custom Keycloak extensions. realmJsonFilePath loads a pre-configured realm. port changes the default port (8080).

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
 plugins: [
  react(),
  keycloakify({
   accountThemeImplementation: "none",
   startKeycloakOptions: {
    // All the options are optional

    /*
    By default Keycloakify uses the official Keycloak Docker Image (quay.io/keycloak/keycloak)
    and lets you select the tag when you run the command by asking you to 
    select a Keycloak version.
    Using this option you can use an alternative Docker Image like the one 
    of Phase2 (https://quay.io/repository/phasetwo/phasetwo-keycloak) and a 
    specific tag to use.
    This option can also be used to pin a specific version of the official 
    Keycloak Docker Image.
    Example: `dockerImage: "quay.io/keycloak/keycloak:25.0.2"`
    */
    dockerImage: "quay.io/phasetwo/phasetwo-keycloak:25.0.2.1721752809",

    /*
    This option allows you to pass extra docker arguments to the 
    `docker run` command.
    */
    dockerExtraArgs: [
     "-e", "KC_HTTP_RELATIVE_PATH=/auth"
    ],

    /*
    This option allows you to start Keycloak with extra arguments.
    */
    keycloakExtraArgs: [
     "--spi-email-template-provider=freemarker-plus-mustache",
     "--spi-email-template-freemarker-plus-mustache-enabled=true",
     "--spi-theme-cache-themes=false"
    ],

    /*
    This option allow you to load custom Keycloak extensions in the 
    Keycloak instance running in the Docker container.
    In this example we load two extensions:
    - https://github.com/InseeFr/Keycloak-FranceConnect
    - https://github.com/micedre/keycloak-mail-whitelisting
    
    (NOTE: ./keycloak-resources/ is just an example, you can use any directory)
    */
    extensionJars: [
     "https://github.com/InseeFr/Keycloak-FranceConnect/releases/download/6.2.0/keycloak-franceconnect-6.2.0.jar",
     "./keycloak-resources/keycloak-mail-whitelisting-2.0.jar"
    ],
    /*
    By default, the Keycloak instance is loaded with a pre-configured 
    realm so you do not have to create a realm, a client, a user, etc.  
    However you might want to edit this base realm configuration and 
    persist the changes that you made.  
    I explain it in this video: https://www.youtube.com/watch?v=lMOLrdqilqE&t=991s
    */
    realmJsonFilePath: "./keycloak-resources/myrealm-realm.json",
    /*
     * By default the Keycloak instance will run on port 8080.
     * This option allows you to change it to another port.
     */
    port: 8081
   }
  })
 ]
});
```

--------------------------------

### Start Storybook locally with npm run storybook

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak

Starts Storybook locally to preview your theme in real time as you make changes.

```bash
npm run storybook
```

--------------------------------

### Install and build commands for yarn

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Runs yarn and then yarn build-keycloak-theme from the monorepo root.

```bash
yarn
yarn build-keycloak-theme
```

--------------------------------

### Install Maven on Ubuntu/Debian using apt

Source: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak

Installs Maven on Ubuntu or Debian using the apt package manager.

```bash
sudo apt-get install maven
```

--------------------------------

### Install dependencies with pnpm

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Install keycloakify and the shadcn login theme package using pnpm.

```bash
pnpm add keycloakify @oussemasahbeni/keycloakify-login-shadcn
```

--------------------------------

### Install @emotion/css

Source: https://docs.keycloakify.dev/common-use-case-examples/changing-the-background-image-css-in-js

Install the @emotion/css package to use CSS-in-JS for styling the login page.

```bash
yarn add @emotion/css
```

--------------------------------

### Start Keycloak with npx keycloakify start-keycloak

Source: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak

Starts a local Keycloak Docker container with your theme preconfigured for testing, including a custom realm and test user.

```bash
npx keycloakify start-keycloak
```

--------------------------------

### Install Keycloakify and Storybook (yarn, pnpm, bun, npm)

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/webpack

Install Keycloakify and optionally Storybook using your preferred package manager. The Storybook installation is optional; if you already have Storybook, ensure `staticDirs: ["../public"]` is set in your `.storybook/main.ts`.

```bash
yarn add keycloakify
# Installing storybook is optional
yarn add --dev rimraf storybook @storybook/react @storybook/react-vite

```

```bash
pnpm add keycloakify
# Installing storybook is optional
pnpm add --dev rimraf storybook @storybook/react @storybook/react-vite

```

```bash
bun add keycloakify
# Installing storybook is optional
bun add --dev rimraf storybook @storybook/react @storybook/react-vite

```

```bash
npm install --save keycloakify
# Installing storybook is optional
npm install --save-dev rimraf storybook @storybook/react @storybook/react-vite

```

--------------------------------

### Install Keycloakify with npm

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Installs keycloakify and optionally Storybook as dev dependencies using npm. Storybook installation is optional.

```bash
npm install keycloakify
# Installing storybook is optional
npm install --save-dev storybook @storybook/react @storybook/react-vite
```

--------------------------------

### Install dependencies with npm

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Install keycloakify and the shadcn login theme package using npm.

```bash
npm install keycloakify @oussemasahbeni/keycloakify-login-shadcn
```

--------------------------------

### Install Keycloakify with pnpm

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Installs keycloakify and optionally Storybook as dev dependencies using pnpm. Storybook installation is optional.

```bash
pnpm add keycloakify
# Installing storybook is optional
pnpm add --dev storybook @storybook/react @storybook/react-vite
```

--------------------------------

### Install Keycloakify with yarn

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Installs keycloakify and optionally Storybook as dev dependencies using yarn. Storybook installation is optional.

```bash
yarn add keycloakify
# Installing storybook is optional
yarn add --dev storybook @storybook/react @storybook/react-vite
```

--------------------------------

### Install dependencies with yarn

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Install keycloakify and the shadcn login theme package using yarn.

```bash
yarn add keycloakify @oussemasahbeni/keycloakify-login-shadcn
```

--------------------------------

### Run dev server

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak-without-storybook

Start the dev server to test the theme. Use `npm run dev`, or `npm run start` for CRA, or `npm run serve` for Angular Webpack.

```bash
npm run dev
# Or 'npm run start' (CRA) or 'npm run serve' (Angular Webpack)
```

--------------------------------

### Install Maven on Fedora using dnf

Source: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak

Installs Maven on Fedora using the dnf package manager.

```bash
sudo dnf install maven
```

--------------------------------

### Install Maven on Windows using Chocolatey

Source: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak

Installs OpenJDK and Maven on Windows using the Chocolatey package manager.

```bash
choco install openjdk
choco install maven
```

--------------------------------

### Clone React starter repository

Source: https://docs.keycloakify.dev/

Clones the keycloakify-starter repository for React. Use this to start a new Keycloakify project with React.

```bash
git clone https://github.com/keycloakify/keycloakify-starter

```

--------------------------------

### Create login story and run Storybook

Source: https://docs.keycloakify.dev/

Commands to install dependencies, add a story for the login page, and run Storybook. Use any package manager; if not using yarn, delete .yarn.lock. Always use npx for CLI tools.

```bash
cd keycloakify-starter

yarn install              # You can use any package manager (npm, pnpm, etc.)
                          # If you do, delete the .yarn.lock file to avoid conflicts.

npx keycloakify add-story # Select login.ftl (for example).
                          # Always use `npx` to run CLI tools installed in your project.
                          # This is standard practice across all modern JS projects,
                          # do not try to adapt this command based on your package 
                          # manager.

npm run storybook         # `npm run <script>`, `yarn <script>`, and `pnpm run <script>`
                          # are strictly equivalent. We use `npm run` here for 
                          # consistency and because `npm` is always available.

```

--------------------------------

### Query the documentation with GitBook ask interface

Source: https://docs.keycloakify.dev/llms.txt

Perform an HTTP GET request to the documentation URL with 'ask' and 'goal' query parameters to get a direct answer and relevant excerpts. 'ask' is the specific question, 'goal' describes the user's ultimate objective.

```HTTP
GET https://docs.keycloakify.dev/index.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Add build script to root package.json

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/turborepo

Add a build-keycloak-theme script and a start-keycloak script to the root package.json to build and start the keycloak theme.

```json
{
  "name": "my-turborepo",
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "build-keycloak-theme": "turbo run build-keycloak-theme --filter=keycloak-theme",
    "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
  },
  // ...
}
```

--------------------------------

### Set environment variables with Bare Metal kc.sh

Source: https://docs.keycloakify.dev/features/environment-variables

Start Keycloak on bare metal with environment variables set inline before the kc.sh start command.

```bash
MY_APP_API_URL="https://api.my-org.com" MY_APP_PALETTE="solaris" /opt/keycloak/bin/kc.sh start

```

--------------------------------

### Install Maven on macOS using Homebrew

Source: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak

Installs Maven on macOS using Homebrew, required to build .jar files for Keycloak theme testing.

```bash
brew install maven
```

--------------------------------

### Docker Compose directory structure and docker-compose.yaml

Source: https://docs.keycloakify.dev/deploying-your-theme

This example shows the directory structure and a docker-compose.yaml file for deploying Keycloak with a custom theme. The theme JAR is mounted from ./themes to /opt/keycloak/providers/.

```text
./docker-compose.yaml
./themes/keycloak-theme-for-kc-all-other-versions.jar
```

```yaml
version: '3.7'

services:
  postgres:
    image: postgres:16.2
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 5432:5432
    networks:
      - keycloak_network

  keycloak:

    image: quay.io/keycloak/keycloak:26.0.4
    command: start-dev

    environment:
      KC_HOSTNAME: ${KEYCLOAK_HOSTNAME}
      KC_HOSTNAME_PORT: 8080
      KC_HTTP_ENABLED: true
      KC_HEALTH_ENABLED: true
      KC_HOSTNAME_STRICT_HTTPS: false
      KC_HOSTNAME_STRICT: false

      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/${POSTGRES_DB}
      KC_DB_USERNAME: ${POSTGRES_USER}
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - 8080:8080
    volumes:
      - ./themes:/opt/keycloak/providers/
    restart: unless-stopped
    depends_on:
      - postgres
    networks:
      - keycloak_network

volumes:
  postgres_data:
    driver: local

networks:
  keycloak_network:
    driver: bridge
```

--------------------------------

### Install Bootstrap with yarn

Source: https://docs.keycloakify.dev/css-customization

Run this command to add Bootstrap as a dependency to your project.

```bash
yarn add bootstrap
```

--------------------------------

### Webpack package.json configuration with startKeycloakOptions

Source: https://docs.keycloakify.dev/features/compiler-options/startkeycloakoptions

Example of configuring startKeycloakOptions in package.json for Webpack. The options mirror the Vite configuration. See the Vite tab for explanations of the options.

```json
{
  "keycloakify": {
    "startKeycloakOptions": {
      "dockerImage": "quay.io/phasetwo/phasetwo-keycloak:25.0.2.1721752809",
      "dockerExtraArgs": [
        "-e",
        "KC_HTTP_RELATIVE_PATH=/auth"
      ],
      "keycloakExtraArgs": [
        "--spi-email-template-provider=freemarker-plus-mustache",
        "--spi-email-template-freemarker-plus-mustache-enabled=true",
        "--spi-theme-cache-themes=false"
      ],
      "extensionJars": [
        "https://github.com/InseeFr/Keycloak-FranceConnect/releases/download/6.2.0/keycloak-franceconnect-6.2.0.jar",
        "./keycloak-resources/keycloak-mail-whitelisting-2.0.jar"
      ],
      "realmJsonFilePath": "./keycloak-resources/myrealm-realm.json",
      "port": 8081
    }
  }
}
```

--------------------------------

### Incorrect asset import example

Source: https://docs.keycloakify.dev/faq/it-works-in-storybook-but-not-in-keycloak

Shows the incorrect way to import assets in Vite or Create React App, which is unreliable and not officially supported.

```html
<img src="/logo.png" />
<img src="logo.png" />
```

--------------------------------

### Vite configuration with keycloakifyBuildDirPath

Source: https://docs.keycloakify.dev/features/compiler-options/keycloakifybuilddirpath

Configure the build directory for .jar files in a Vite project. The default is ./dist_keycloak. This example sets it to ./keycloak-theme-dist.

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
      keycloakifyBuildDirPath: "./keycloak-theme-dist"
    })
  ],
})
```

--------------------------------

### Workspace configuration in pnpm-workspace.yaml

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Defines the packages list in pnpm-workspace.yaml to include apps/* and packages/* directories. Required for pnpm monorepo setup.

```yaml
packages:
  - "apps/*"
  - "packages/*"
```

--------------------------------

### Webpack configuration with keycloakifyBuildDirPath

Source: https://docs.keycloakify.dev/features/compiler-options/keycloakifybuilddirpath

Configure the build directory for .jar files in a Webpack project. The default is ./build_keycloak. This example sets it to ./keycloak-theme-jars.

```json
{
    "keycloakify": {
        "keycloakifyBuildDirPath": "./keycloak-theme-jars"
    }
}
```

--------------------------------

### Add postinstall script to package.json

Source: https://docs.keycloakify.dev/features/compiler-options/kccontextexclusionsftl

Add a postinstall script to package.json that runs patch-package. This ensures the patch is applied automatically after every install.

```json
{
    "name": "keycloakify-starter",
    "scripts": {
        "postinstall": "patch-package",
        "dev": "vite",
    ...
}

```

--------------------------------

### package.json scripts for building Keycloak theme and Storybook

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Add scripts to package.json for building the Keycloak theme and starting Storybook. The build-keycloak-theme script runs the build and then keycloakify build.

```JSON
{
  "name": "my-react-app",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview",
    "build-keycloak-theme": "npm run build && keycloakify build",
    "storybook": "storybook dev -p 6006"
  },
  // ...
```

--------------------------------

### Run keycloakify build with --project option

Source: https://docs.keycloakify.dev/features/compiler-options/project

Use this command to run the keycloakify build subcommand from the root of a monorepo, specifying the path to the Keycloakify project (e.g., packages/keycloak-theme). The --project (or -p) option is required for monorepo setups.

```bash
npx keycloakify build -p <path>
```

--------------------------------

### After: usePrepareTemplate prototype in src/keycloak-theme/account/Template.css

Source: https://docs.keycloakify.dev/release-notes-and-upgrade-instructions/v7-greater-than-v8

Updated usePrepareTemplate call for the account theme with styles array using url.resourcesCommonPath and url.resourcesPath.

```css
"styles": [
    `${url.resourcesCommonPath}/node_modules/patternfly/dist/css/patternfly.min.css`,
    `${url.resourcesCommonPath}/node_modules/patternfly/dist/css/patternfly-additions.min.css`,
    `${url.resourcesPath}/css/account.css`
],
```

--------------------------------

### Original src/index.tsx entry point

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/webpack

Example of a typical `src/index.tsx` entry point in a Create React App project. This is the file you will rename to `src/index.app.tsx` and modify to conditionally render the Keycloakify theme when `kcContext` is defined.

```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { MyProvider } from "./MyProvider";
import reportWebVitals from './reportWebVitals';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(
  <React.StrictMode>
    <MyProvider>
      <App />
    </MyProvider>
  </React.StrictMode>
);

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

```

--------------------------------

### Navigate into the project directory

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Change into the newly created project directory named 'keycloak-theme'.

```bash
cd keycloak-theme
```

--------------------------------

### Key commands with bun

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run Storybook, build the theme, and test in local Keycloak using bun.

```bash
# Run Storybook for component development and testing
bun run storybook

# Build the JAR file to import in Keycloak, see https://docs.keycloakify.dev/deploying-your-theme
bun run build-keycloak-theme

# Test in a local Keycloak. More info: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak
bunx keycloakify start-keycloak
```

--------------------------------

### Before: usePrepareTemplate prototype in src/keycloak-theme/account/Template.css

Source: https://docs.keycloakify.dev/release-notes-and-upgrade-instructions/v7-greater-than-v8

Original usePrepareTemplate call for the account theme with stylesCommon and styles arrays. Replace with the updated version.

```css
url,
"stylesCommon": ["node_modules/patternfly/dist/css/patternfly.min.css", "node_modules/patternfly/dist/css/patternfly-additions.min.css"],
"styles": ["css/account.css"],
```

--------------------------------

### public/index.html with keycloakify-ignore markers

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/webpack

Example HTML head for a Keycloakify project. The title and environment variable script are wrapped in keycloakify-ignore-start/end comments so Keycloakify excludes them from the generated Keycloak pages.

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <link rel="icon" href="%PUBLIC_URL%/icon.png" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="theme-color" content="#000000" />
  <link rel="apple-touch-icon" href="%PUBLIC_URL%/icon.png" />
  <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />

  <meta name="keycloakify-ignore-start">
  <title>ACME Dashboard</title>
  <script>
    window.ENV = {
      API_ADDRESS: '${API_ADDRESS}',
      SENTRY_DSN: '${SENTRY_DSN}'
    };
  </script>
  <meta name="keycloakify-ignore-end">

  <!-- ... -->

</head>

<!-- ... -->
```

--------------------------------

### React/MUI KcPage using getIsDark to switch themes

Source: https://docs.keycloakify.dev/common-use-case-examples/dark-mode-persistence

Example of integrating the `getIsDark` utility in a Keycloak login page with React and MUI. It creates dark and light themes and wraps the page in a `ThemeProvider` based on the dark mode preference.

```tsx
import type { KcContext } from "./KcContext";
import { useI18n } from "./i18n";
import DefaultPage from "keycloakify/login/DefaultPage";
import Template from "keycloakify/login/Template";
import { createTheme, ThemeProvider } from "@mui/material/styles";
import { getIsDark } from "../shared/isDark";
const UserProfileFormFields = lazy(() => import("keycloakify/login/UserProfileFormFields"));

const doMakeUserConfirmPassword = true;

const theme_dark = createTheme({
    palette: {
        mode: "dark"
    }
});
const theme_light = createTheme({
    palette: {
        mode: "light"
    }
});

export default function KcPage(props: { kcContext: KcContext }) {
    return (
        <ThemeProvider theme={getIsDark() ? theme_dark : theme_light}>
            <KcPageContextualized {...props} />
        </ThemeProvider>
    );
}

function KcPageContextualized(props: { kcContext: KcContext }) {
    const { kcContext } = props;
    const { i18n } = useI18n({ kcContext });

    return (
        <Suspense>
            {(() => {
                switch (kcContext.pageId) {
                    default:
                        return (
                            <DefaultPage
                                kcContext={kcContext}
                                i18n={i18n}
                                classes={classes}
                                Template={Template}
                                doUseDefaultCss={true}
                                UserProfileFormFields={UserProfileFormFields}
                                doMakeUserConfirmPassword={doMakeUserConfirmPassword}
                            />
                        );
                }
            })()}
        </Suspense>
    );
}
```

--------------------------------

### postBuild hook with file-based logging for debugging

Source: https://docs.keycloakify.dev/features/compiler-options/postbuild

Example of using the postBuild hook to write logs to a file because console.log does not work in the hook's thread. The log file is created at the project root.

```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { keycloakify } from "keycloakify/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [
        react(),
        keycloakify({
            accountThemeImplementation: "Single-Page",
            postBuild: async (buildContext) => {

                const fs = await import("fs");
                const path = await import("path");

                const logFilePath = path.join(buildContext.projectDirPath, "postBuildLog.txt");

                fs.rmSync(logFilePath, { force: true });

                const log= (msg: string) => {
                    fs.appendFileSync(
                        logFilePath,
                        Buffer.from(msg + "\n", "utf8")
                    );
                };

                // This will be logged into postBuildLog.txt at the root of your project.
                log("Hello World");

            }
        })
    ]
});
```

--------------------------------

### Set environment variables with Docker

Source: https://docs.keycloakify.dev/features/environment-variables

Run Keycloak with Docker, passing the environment variables MY_APP_API_URL and MY_APP_PALETTE using --env flags. Note the missing backslash before -p in the original example.

```bash
docker run \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    --env MY_APP_API_URL='https://api.my-org.com' \
    --env MY_APP_PALETTE='solaris'
    -p 8080:8080 \
    start --optimized

```

--------------------------------

### Migrate i18n setup from createUseI18n to i18nBuilder

Source: https://docs.keycloakify.dev/release-notes-and-upgrade-instructions

Shows the diff for src/login/i18n.ts. Replace createUseI18n with i18nBuilder, add withThemeName<ThemeName>(), and export useI18n and type I18n. Note that the syntax highlighting for diffs may be buggy; rely on the + and - symbols.

```diff
-import { createUseI18n } from "keycloakify/login";
+import { i18nBuilder } from "keycloakify/login";
+import type { ThemeName } from "../kc.gen";


-export const { useI18n, ofTypeI18n } = createUseI18n({
+const { useI18n, ofTypeI18n } = i18nBuilder
+    .withThemeName<ThemeName>()
+    .withCustomTranslations({
        en: {
          backToLogin: "⏪ Back to <strong>Login page</strong>",
          myCustomKey: "My custom message",
        },
        fr: {
          backToLogin: "⏪ Retour à la <strong>page de Login</strong>",
          myCustomKey: "Mon message personalisé",
        },
     })
+    .build()
      
-export type I18n = typeof ofTypeI18n;
+type I18n = typeof ofTypeI18n;

+export { useI18n, type I18n };
```

--------------------------------

### Vite configuration with Keycloakify plugin

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Configure Vite to use the Keycloakify plugin. The example sets accountThemeImplementation to "none" and does not provide other build options, but you likely want to define keycloakVersionTargets.

```TypeScript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { keycloakify } from "keycloakify/vite-plugin";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(), 
    keycloakify({
        accountThemeImplementation: "none"
    })
  ],
})
```

--------------------------------

### Create Nx workspace with Vite starter

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/nx

Initializes a new Nx workspace with the React monorepo preset and Vite bundler.

```bash
npx create-nx-workspace@latest --preset=react-monorepo --bundler=vite
```

--------------------------------

### Move starter template files into project

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Clones the keycloakify-starter template and moves relevant files into the project. If Storybook is already set up, skip the .storybook move but ensure staticDirs: ["../public"] is present.

```bash
cd my-react-app
git clone https://github.com/keycloakify/keycloakify-starter tmp
mv tmp/src src/keycloak-theme

# Note for the following command: If you already have Storybook setup
# in your project you can skip this.
# Only make sure you have `staticDirs: ["../public"]` in your .storybook/main.ts
mv tmp/.storybook .

rm -rf tmp
rm src/keycloak-theme/vite-env.d.ts
mv src/keycloak-theme/main.tsx src/main.tsx
```

--------------------------------

### Initialize Git repository

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Initialize a Git repository, stage all files, and create the initial commit.

```bash
git init .
git add -A
git commit -m "Initial commit"
```

--------------------------------

### Key commands with npm

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run Storybook for component development, build the Keycloak theme JAR, and test in a local Keycloak using npm.

```bash
# Run Storybook for component development and testing
# IMPORTANT! Must be run at least once.
npm run storybook

# Build the JAR file to import in Keycloak, see https://docs.keycloakify.dev/deploying-your-theme
npm run build-keycloak-theme

# Test in a local Keycloak. More info: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak
npx keycloakify start-keycloak
```

--------------------------------

### Key commands with pnpm

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run Storybook, build the theme, and test in local Keycloak using pnpm.

```bash
# Run Storybook for component development and testing
pnpm storybook

# Build the JAR file to import in Keycloak, see https://docs.keycloakify.dev/deploying-your-theme
pnpm build-keycloak-theme

# Test in a local Keycloak. More info: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak
pnpm exec keycloakify start-keycloak
```

--------------------------------

### Initialize Multi-Page Account Theme

Source: https://docs.keycloakify.dev/theme-types/account-theme/multi-page

Run this command to initialize the Multi-Page Account theme. When prompted, select 'Multi-Page'. This creates the necessary boilerplate.

```bash
npx keycloakify initialize-account-theme
```

--------------------------------

### Initialize Keycloakify with bun

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run the Keycloakify initialization command using bunx.

```bash
bunx keycloakify init
```

--------------------------------

### Initialize native email theme with FreeMarker

Source: https://docs.keycloakify.dev/theme-types/email-theme

Run this command to initialize a native email theme in the 'src/email' directory. Select the 'native' option when prompted.

```bash
npx keycloakify initialize-email-theme
```

--------------------------------

### Build custom Docker image with Keycloak theme

Source: https://docs.keycloakify.dev/deploying-your-theme

Creates a Dockerfile that builds the theme JAR using Node and Maven, then copies it into a Keycloak image and runs kc.sh build. Includes commands to clone the starter project, create the .dockerignore, build the image, and run it with admin credentials.

```bash
cd ~/github
git clone https://github.com/keycloakify/keycloakify-starter
cd keycloakify-starter

cat << EOF > ./.dockerignore
node_modules
dist
dist_keycloak
# IMPORTANT: Make sure `.gitignore` is **not** listed
# in your .dockerignore file
EOF

cat << EOF > ./Dockerfile
FROM node:20-alpine as build
RUN apk update && \
    apk add --no-cache openjdk17 maven
WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile
RUN yarn build-keycloak-theme

FROM quay.io/keycloak/keycloak:26.0.7
WORKDIR /opt/keycloak
COPY --from=build /app/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start", "--optimized"]
EOF

docker build -t my-keycloak .
docker run \
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
    -p 8080:8080 \
    my-keycloak
```

--------------------------------

### Before: usePrepareTemplate prototype in src/keycloak-theme/login/Template.tsx

Source: https://docs.keycloakify.dev/release-notes-and-upgrade-instructions/v7-greater-than-v8

Original usePrepareTemplate call with url, stylesCommon, and styles arrays. Replace this with the updated version that uses url.resourcesCommonPath and url.resourcesPath.

```tsx
url,
"stylesCommon": [
    "node_modules/patternfly/dist/css/patternfly.min.css",
    "node_modules/patternfly/dist/css/patternfly-additions.min.css",
    "lib/zocial/zocial.css"
],
"styles": ["css/login.css"],
```

--------------------------------

### Initialize Keycloakify with npx

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run the Keycloakify initialization command using npx. This sets up the theme structure.

```bash
npx keycloakify init
```

--------------------------------

### Create a new Vite project with bun

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run this command to scaffold a new Vite project using bun.

```bash
bun create vite
```

--------------------------------

### package.json - Keycloakify scripts and configuration

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/webpack

This package.json snippet shows the required scripts for Keycloakify (prestart, prestorybook, prebuild, postbuild, build-keycloak-theme) and the keycloakify configuration object. The configuration includes accountThemeImplementation, projectBuildDirPath, staticDirPathInProjectBuildDirPath, and publicDirPath. The scripts use keycloakify commands like update-kc-gen and copy-keycloak-resources-to-public.

```json
{
    "name": "my-app",
    "scripts": {
        "prestart": "keycloakify update-kc-gen && keycloakify copy-keycloak-resources-to-public",
        "start": "react-scripts start",
        "prestorybook": "npm run prestart",
        "storybook": "storybook dev -p 6006",
        "prebuild": "keycloakify update-kc-gen",
        "build": "react-scripts build",
        "postbuild": "rimraf build/keycloakify-dev-resources",
        "build-keycloak-theme": "npm run build && keycloakify build",
        "format": "prettier . --write"
        // ...
    },
    "keycloakify": {
        "accountThemeImplementation": "none",
        "projectBuildDirPath": "build",
        "staticDirPathInProjectBuildDirPath": "static",
        "publicDirPath": "public"
    },
    // ...
```

--------------------------------

### Override locale in getKcContextMock

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak-without-storybook

Example of using the `overrides` parameter to change the `kcContext.locale.currentLanguageTag` to preview the page in a different language, here Chinese (zh-CN).

```tsx
window.kcContext = getKcContextMock({
  pageId: "login.ftl",
  overrides: {
    locale: {
      currentLanguageTag: "zh-CN",
    },
  },
});
```

--------------------------------

### Key commands with yarn

Source: https://docs.keycloakify.dev/starter-themes/shadcn-ui-tailwind

Run Storybook, build the theme, and test in local Keycloak using yarn.

```bash
# Run Storybook for component development and testing
yarn storybook

# Build the JAR file to import in Keycloak, see https://docs.keycloakify.dev/deploying-your-theme
yarn build-keycloak-theme

# Test in a local Keycloak. More info: https://docs.keycloakify.dev/testing-your-theme/inside-of-keycloak
npx keycloakify start-keycloak
```

--------------------------------

### Original src/main.tsx before modification

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/vite

Example of a typical src/main.tsx file before modification. This file is renamed to src/main.app.tsx and modified as shown in the next snippet.

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import "./index.css";
import { MyProvider } from "./MyProvider";

createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <MyProvider>
        <App />
      </MyProvider>
    </StrictMode>,
);
```

--------------------------------

### Copy Keycloakify starter sources into Nx app

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/nx

Clones the Keycloakify starter repository and moves its src and .storybook directories into the keycloak-theme app, then removes the temporary clone.

```bash
cd nx-monorepo
rm -rf apps/keycloak-theme/src
git clone https://github.com/keycloakify/keycloakify-starter tmp
mv tmp/src apps/keycloak-theme
mv tmp/.storybook apps/keycloak-theme
rm -rf tmp
```

--------------------------------

### Clone Svelte starter repository

Source: https://docs.keycloakify.dev/

Clones the keycloakify-starter-svelte repository and renames it to keycloakify-starter. Credit goes to @luca-peruzzo for Svelte support.

```bash
git clone https://github.com/keycloakify/keycloakify-starter-svelte keycloakify-starter

```

--------------------------------

### Root package.json scripts for bun

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Adds build-keycloak-theme and start-keycloak scripts using bun run --cwd and keycloakify CLI.

```json
{
   "name": "my-monorepo",
   "scripts": {
       "build-keycloak-theme": "bun run --cwd apps/keycloak-theme build-keycloak-theme",
       "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
   },
   // ...
}
```

--------------------------------

### After: usePrepareTemplate prototype in src/keycloak-theme/login/Template.tsx

Source: https://docs.keycloakify.dev/release-notes-and-upgrade-instructions/v7-greater-than-v8

Updated usePrepareTemplate call with styles array using url.resourcesCommonPath and url.resourcesPath. This replaces the previous version.

```tsx
"styles": [
    `${url.resourcesCommonPath}/node_modules/patternfly/dist/css/patternfly.min.css`,
    `${url.resourcesCommonPath}/node_modules/patternfly/dist/css/patternfly-additions.min.css`,
    `${url.resourcesCommonPath}/lib/zocial/zocial.css`,
    `${url.resourcesPath}/css/login.css`
],
```

--------------------------------

### Initialize Single-Page Account Theme

Source: https://docs.keycloakify.dev/theme-types/account-theme/single-page

Run this command to initialize a Single-Page account theme. Select 'Single-Page' when prompted.

```bash
npx keycloakify initialize-account-theme # Select 'Sigle-Page'
```

--------------------------------

### Add patch-package as dev dependency

Source: https://docs.keycloakify.dev/features/compiler-options/kccontextexclusionsftl

Install patch-package as a dev dependency using yarn. This is the first step in setting up patch-package to persist the template changes.

```bash
yarn add --dev patch-package

```

--------------------------------

### Generate Angular application and copy Keycloakify starter template

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/angular-workspace

Commands to create a new Angular application named 'keycloak-theme', remove its default public and src directories, clone the keycloakify-starter-angular-vite repository, and move its src, public, vite.config.ts, and index.html into the project.

```bash
cd my-workspace
yarn ng generate application keycloak-theme
rm -rf projects/keycloak-theme/public
rm -rf projects/keycloak-theme/src
git clone https://github.com/keycloakify/keycloakify-starter-angular-vite tmp
mv tmp/src projects/keycloak-theme
mv tmp/public projects/keycloak-theme
mv tmp/vite.config.ts projects/keycloak-theme
mv tmp/index.html projects/keycloak-theme
rm -rf tmp
```

--------------------------------

### Vite: Change background image with import.meta.env.BASE_URL

Source: https://docs.keycloakify.dev/common-use-case-examples/changing-the-background-image-css-in-js

Vite example: change the login page background image by referencing a file in the public directory using import.meta.env.BASE_URL.

```tsx
import { css } from "@emotion/css";
import { Suspense, lazy } from "react";
// ...
export default function KcPage(props: { kcContext: KcContext }) {
    const { kcContext } = props;    
    // ...
    return (
        // ...
        <DefaultPage
            kcContext={kcContext}
            classes={classes}
            // ...
        />
    );
}

const classes = {
    kcBodyClass: css({
        "&&": { // Increase specificity so our rule takes precedence over the default background.
            background: `url(${import.meta.env.BASE_URL}background.png) no-repeat center center fixed`,
        }
    })
} satisfies { [key in ClassKey]?: string };
```

--------------------------------

### Workspace configuration in package.json for yarn/npm/bun

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/package-manager-workspaces

Defines the workspaces array in the root package.json to include apps/* and packages/* directories. This is required for monorepo setup with yarn, npm, or bun.

```json
{
  "name": "my-monorepo",
  "workspaces": [
    "apps/*"
    "packages/*"
  ],
  "private": true,
```

--------------------------------

### Repatriate starter template files into your project

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/webpack

Repatriate the relevant files from the keycloakify-starter-webpack template into your project. This clones the starter, moves its `src` to `src/keycloak-theme`, optionally moves `.storybook`, removes temporary files, and renames the theme's entry point to `src/index.tsx`.

```bash
cd my-app
git clone https://github.com/keycloakify/keycloakify-starter-webpack tmp
mv tmp/src src/keycloak-theme

# Note for the following command: If you already have Storybook setup
# in your project you can skip this.
# Only make sure you have `staticDirs: ["../public"]` in your .storybook/main.ts
mv tmp/.storybook .

rm -rf tmp
rm src/keycloak-theme/react-app-env.d.ts
mv src/keycloak-theme/index.tsx src/index.tsx

```

--------------------------------

### Svelte story for login page with Chinese locale

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak

Example story file for the login page in Svelte, showing a default story and an InChinese story that overrides the locale to zh-CN.

```Svelte
<script
  context="module"
  lang="ts"
>
  import { defineMeta } from '@storybook/addon-svelte-csf';
  import type { KcPageStoryProps } from '../KcPageStory';
  import KcPageStory from '../KcPageStory.svelte';

  const args: KcPageStoryProps = { pageId: 'login.ftl' };
  const { Story } = defineMeta({
    title: 'login/login.ftl',
    component: KcPageStory,
    args: args,
  });
</script>

<Story name="Default" />

<Story
  name="InChinese"
  args={{
    ...args,
    kcContext: {
      locale: {
        currentLanguageTag: "zh-CN"
      }
    }
  }}
/>
```

--------------------------------

### Angular story for register page with Chinese locale

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak

Example story file for the register page in Angular, showing a default story and an InChinese story that overrides the locale to zh-CN.

```TypeScript
import { Meta, StoryObj } from '@storybook/angular';
import { decorators, KcPageStory } from '../KcPageStory';
import { Attribute } from 'keycloakify/login';

const meta: Meta<KcPageStory> = {
    title: 'login/register.ftl',
    component: KcPageStory,
    decorators: decorators,
    globals: {
        pageId: 'register.ftl'
    }
};

export default meta;

type Story = StoryObj<KcPageStory>;

export const Default: Story = {};

export const InChinese: Story = {
    globals: {
        kcContext: {
            locale: {
                    currentLanguageTag: "zh-CN"
            }
        }
    }
};
```

--------------------------------

### React story for register page with Chinese locale

Source: https://docs.keycloakify.dev/testing-your-theme/outside-of-keycloak

Example story file for the register page in React, showing a default story and an InChinese story that overrides the locale to zh-CN.

```TypeScript
import type { Meta, StoryObj } from "@storybook/react";
import { createKcPageStory } from "../KcPageStory";

const { KcPageStory } = createKcPageStory({ pageId: "register.ftl" });

const meta = {
    title: "login/register.ftl",
    component: KcPageStory
} satisfies Meta<typeof KcPageStory>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {
    render: () => <KcPageStory />
};

export const InChinese: Story = {
    render: ()=> (
        <KcPageStory
            kcContext={{
                locale: {
                    currentLanguageTag: "zh-CN"
                }
            }}
        />
    )
};
```

--------------------------------

### Test locally with start-keycloak CLI

Source: https://docs.keycloakify.dev/features/environment-variables

Pass environment variables to the start-keycloak command for local testing.

```bash
MY_APP_PALETTE="solaris" MY_APP_API_URL="..." npx keycloakify start-keycloak

```

--------------------------------

### Run Keycloakify build with project path

Source: https://docs.keycloakify.dev/integration-keycloakify-in-your-codebase/angular-workspace

Use this command in the workspace root to build the Keycloakify theme, specifying the project path with --project.

```bash
npx keycloakify build --project projects/keycloak-theme
```
Tokens:
Raw