How keycloakify/keycloakify works
Project Type and Purpose
• This project is a build tool and theme generator tailored to create customized themes for Keycloak. It provides both account and login UI theming, along with an ecosystem of scripts, utilities, and build tools to integrate, generate, and preview themes.
• The README and file structure indicate that Keycloakify is not a traditional full-stack application but rather a specialized compiler/toolchain for theming, complete with Storybook integration for component previews and a rich library of scripts to support various customization workflows.
Main Components
a. Theme Source Components:
• Account Theming Module – under src/account: This includes context providers, templates, pages, and library functions dedicated to the Keycloak account console.
• Login Theming Module – under src/login: Contains the login context, templates, various login pages (like Login, LogoutConfirm, Register, etc.), and internationalization (i18n) support.
b. Build & Compiler Infrastructure:
• Bin and Scripts – under src/bin and scripts: These directories hold the build scripts, theme initialization utilities (like initialize-account-theme, initialize-admin-theme, initialize-email-theme), and tooling to package and customize themes.
• Keycloakify-Specific Compiler Tools – subdirectories under src/bin/keycloakify (with buildJars, generateFtl, generateResources, replacers, and others). They manage the transformation of theme source code into assets and deployable formats.
c. Utility and Shared Libraries:
• Core Utilities – under src/lib and src/tools: Utility functions such as class name management (kcClsx), sanitizers for HTML content (kcSanitize), and additional helper functions.
• Shared Components and Contexts for both modules (account and login) such as the KcContext implementations and mocks.
d. Preview, Documentation, and Storybook:
• Storybook Configuration – under .storybook and stories directories: This provides a live preview environment for UI components and theme templates.
• Test and Documentation – directories like test and README provide insights into expected behaviors and include documentation and testing code (vitest, type-level tests, etc.).
e. Configuration and Dependency Management:
• Package files (package.json, tsconfig.json, etc.) and CI/CD workflows (under .github/workflows) which hint at the external dependencies and automated processes in the build and deploy cycle.
Relationships & Interactions
• The Compiler/Build Tools (scripts, bin) transform the source theme components (in account, login, lib) into deployable assets that can be used by a Keycloak server.
• The generated themes integrate with Keycloak (compatible with various versions as stated in the README), so the output of these tools is configured for consumption by Keycloak.
• Storybook and the stories directory provide a feedback and preview loop for developers to view theme changes live.
• Utility libraries support both theme modules by providing common functionality such as context sanitation, dynamic class management, and i18n support.
• External integrations include CI/CD pipelines (GitHub Actions), dependency management (npm, renovate.json), and documentation portals (Hosted Storybook, Documentation linked in README).
Architectural Patterns and Design Principles
• Modular Structure: Separation between account and login themes, with discrete directories for each helps maintain separation of concerns.
• Build Tool Pipeline: A complex pipeline where source code is processed through multiple scripts (e.g., generating FreeMarker template files, managing imports in CSS/JS through replacers) indicative of a compiler-like design.
• Extensibility: The design is extensible through a modular structure and dedicated extension points (e.g., sync-extensions scripts) to support different Keycloak versions.