📖Build options
package.json
options
package.json
optionsYou can read here the package.json fields that are used by Keyclaokify.
extraPages
extraPages
Tells Keycloakify to generate extra pages. If you are unsure what it means, please read this.
If you have in your package.json
:
Keycloakify will generate my-extra-page-1.ftl
and my-extra-page-2.ftl
alongside login.ftl
, register-user-profile.ftl
ect...
More info about this in this section (I do it only for my project).
extraThemeProperties
extraThemeProperties
By default the theme.properties
files located in build_keycloak/src/main/resources/theme/<your app>/login/theme.properties
only contains:
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:
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.
bundler
Introduced in 6.11.4
Configure if you want Keycloakify to build the final .jar
for you or not.
Possibles values are:
"keycloakify"
(default): Keycloakify will build the .jar file."none"
: Keycloakify will not create a .jar file."mvn"
(legacy): Keycloakify will use Maven to bundle the .jar file. This option is to use only if you experience problem with "keycloakify". It require mvn to be installed. If you have to resort to this option please open an issue about it so we can see wha't wrong with our way of building the.jar
file.
You can also convigure this value using an environement variable:
groupId
Introduced in 6.11
Configure the groupId
that will appear in the pom.xml
file.
By default it's the package.json hompage field at reverse with .keycloak at the end.
You can overwrite this using an environement variable:
artifactId
Introduced in 6.11
Configure the artifactId
that will appear in the pom.xml
file.
By default it's <themeName>-keycloak-theme
See, keycloak.themeName
option.
You can overwrite this using an environement variable:
The artifactId
also affects the name of the .jar
file.
keycloakVersionDefaultAssets
Default: 11.0.3
Only use this param if you know what you are doing. See related issue.
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
But you can overwrite this value using an environnement variable (Introduced in 6.11):
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:
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"]
extraThemeNames
Introduced in 7.12
This option 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 active:
areAppAndKeycloakServerSharingSameDomain
(deprecated)
areAppAndKeycloakServerSharingSameDomain
(deprecated)This option is only considered when building with --external-assets
.
Set to true
it tels Keycloakify that you have configured your reverse proxy so that your app and your Keycloak server are under the same domain, example:
https://example.com/auth: Keycloak.
https://example.com (or https://example.com/x/y/z): Your App
Example:
When enabled you don't need to specify a homepage
field in the package.json
CLI options
Options that can be passed to the npx keycloakify
command.
--silent
--silent
Prevent the build command from generating outputs.
--external-assets
(deprecated)
--external-assets
(deprecated)This is for performance optimisation.
Build the theme without bundling the assets (static js files, images ect). Keycloakify will read the package.json
-> homepage
field to know from where the assets should be downloaded.
This enables to you to levrage CDN and cache big resource files that are used by both the main app and the login pages.
Step to make --external-assets
work:
Provide the url of your app in the
homepage
field ofpackage.json
example or in apublic/CNAME
file example. (Or usekeycloakify.areAppAndKeycloakServerSharingSameDomain=true
)
Build the theme using
npx keycloakify --external-assets
ex(Optional) Enable long-term assets caching on the server hosting your app. This is how you would do it with Ngnix.
Make sure not to build your app and the keycloak theme separately (run
yarn build-keycloak-theme
only once in your CI) and remember to update the Keycloak theme every time you update your app.Be mindful that if your app is down your login pages are down as well.
Checkout a complete setup here
Last updated