Links
📖

Build options

--project or -p CLI option

Introduced in Keycloakify 9.4
This option is for Monorepos. You can run Keycloakify from the root of your project with:
npx keycloakify --project <path>
<path> would be tipically something like packages/keycloak-theme

extraThemeProperties

By default the theme.properties files located in build_keycloak/src/main/resources/theme/<your app>/login/theme.properties only contains:
parent=keycloak
If, for some reason, you need to add extra properties like for example env=dev you can do it by editing your package.json this way:
package.json
{
"keycloakify": {
"extraThemeProperties": [
"env=dev",
"locales=en,ko",
"foo=bar",
"myValue=${env.MY_ENV_VARIABLE:default}"
]
}
}
You can then access this property in the kcContext (kcContext.properties.foo === "bar") even if you won't have type safety.
If you want to have your custom properties listed on the kcContext (at the type level) you can augment the KcContext type definition. More info.
You can also use it to access Keycloak environment variables in your theme. More info. You can find here a practical example of environment variables.

doCreateJar

default: true
Introduced in 9.0
Tell wether or not you want Keycloakify to bundle your theme within a .jar file.
package.json
{
"keycloakify": {
"doCreateJar": false
}
}

groupId

Introduced in 6.11
Configure the groupId that will appear in the pom.xml file.
package.json
{
"keycloakify": {
"groupId": "dev.keycloakify.demo-app-advanced.keycloak"
}
}
By default it's the package.json hompage field at reverse with .keycloak at the end.
You can overwrite this using an environement variable:
KEYCLOAKIFY_GROUP_ID="com.your-company.your-project.keycloak" npx keycloakify

artifactId

Introduced in 6.11
Configure the artifactId that will appear in the pom.xml file.
package.json
{
"keycloakify": {
"artifactId": "keycloakify-advanced-starter-keycloak-theme"
}
}
By default it's <themeName>-keycloak-theme See, keycloak.themeName option.
You can overwrite this using an environement variable:
KEYCLOAKIFY_ARTIFACT_ID="my-cool-theme" npx keycloakify
The artifactId also affects the name of the .jar file.

loginThemeResourcesFromKeycloakVersion

Default: 11.0.3
This replaces keycloakVersionDefaultAssets.
The default login Template.tsx imports CSS resources that are copied from the Keycloak version specified by this parameter. This is not something you should worry about too much. These imports are mostly there so that the pages that Keycloakify provides by default match the ones of the default theme. You should, however, strive to use your own assets; after all, this is the point of creating a theme. Example where Keycloak resources are imported in the login theme:
package.json
{
"keycloakify": {
"loginThemeResourcesFromKeycloakVersion": "21.0.1"
}
}
Note that for account theme we do not enable to specify the version, the assets used are fixed to Keycloak 21.1.2.

version

Configure the version that will appear in the pom.xml file.
By default the version that is used is the one in the package.json of your project
package.json
{
"version": "1.3.4"
}
But you can overwrite this value using an environnement variable (Introduced in 6.11):
KEYCLOAKIFY_THEME_VERSION="4.5.6" npx keycloakify
The version also affects the name of the .jar file.

customUserAttributes

Deprecated.
Introduced in 7.4.0 removed in 7.13.0
Keycloakify now analyzes your code and see what field name are actually used. Just make sure your fieldNames aren't generated at runtime. Eg:
// OK ✅
messagesPerField.exists("foo-bar")
// Not OK 🛑
const bar= "bar";
messagesPerField.exists(`foo-${bar}`);

themeName

Introduced in 7.5.0
This is the name of the theme in the Keycloak admin select:
By default it's package.json["name"]
package.json
{
"keycloakify": {
"themeName": "my-custom-name"
}
}
You can also provide an array if you want to Keycloakify to create multiple theme variant:
package.json
{
"keycloakify": {
"themeName": [ "keycloakify-starter", "keycloakify-starter-variant-1" ]
}
}
This option deprecates extraThemeNamesand let you pack multiple themes variant in a single .jar bundle. In vanilla Keycloak themes you have the ability to extend a base theme. There is now an idiomatic way of achieving the same result by using this option.
This will make the theme variant appear in the Keycloak admin select input:
The theme name will be available on the kcContext:
You'll be able to implement different behaviour based on which theme variant is the current one:
To load different global css file based on the theme name you can implement this strategy:
// src/keycloak-theme/login/useGlobalStylesheet.ts
import { useMemo } from "react";
export function useGlobalStylesheet(themeName: string){
useMemo(() => {
switch(themeName){
case "keycloakify-starter":
// @ts-expect-error
import("./keycloakify-starter.css");
break;
case "keycloakify-starter-variant-1":
// @ts-expect-error
import("./keycloakify-starter-variant-1.css");
break;
}
}, [themeName]);
}
// src/keycloak-theme/login/KcApp.tsx
import { useGlobalStylesheet } from "./useGlobalStylesheet";
// ...
export default function KcApp(props: { kcContext: KcContext; }) {
const { kcContext }= props;
// ...
useGlogalStylesheet(kcContext.themeName);
// ...

silent

Options that can be passed to the npx keycloakify command. With npx keycloakify --silent no output is printed to the console.

XDG_CACHE_HOME

Keycloakify needs to download resources from the Keycloak project to build your theme. To prevent these resources from being downloaded repeatedly, Keycloakify caches them by default in node_modules/.cache. However, you can specify a different location by setting the XDG_CACHE_HOME environment variable. Example: XDG_CACHE_HOME=/home/runner/.cache/yarn npx keycloakify
This is particularly useful in your CI workflow to ensure that the cache persists across runs (see the documentation for the bahmutov/npm-install GitHub Action).

PUBLIC_DIR_PATH

Default: ~/public
Example: npx PUBLIC_DIR_PATH=./web/public npx copy-keycloak-resources-to-public
Cloud IAM - Keycloak Identity and Access Management as a Service
Feeling overwhelmed? Check out our exclusive sponsor's Cloud IAM consulting services to simplify your experience.