📖Build options

CLI options

Options that can be passed to the npx keycloakify command.

--external-assets

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 of package.json example or in a public/CNAME file example. (Or use keycloakify.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

--silent

Prevent the build command from generating outputs.

package.json options

You can read here the package.json fields that are used by Keyclaokify.

keycloakify.extraPages

Tells Keycloakify to generate extra pages.

If you have in your package.json:

package.json

{
    "keycloakify": {
        "extraPages": [ 
            "my-extra-page-1.ftl", 
            "my-extra-page-2.ftl" 
        ]
    }
}

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).

keycloakify.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"
        ]
    }
}

keycloakify.areAppAndKeycloakServerSharingSameDomain

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:

package.json

{
    "keycloakify": {
        "areAppAndKeycloakServerSharingSameDomain": true
    }
}

When enabled you don't need to specify a homepage field in the package.json

keycloakify.bundler

Introduced in 6.11.4

Configure if you want Keycloakify to build the final .jar for you or not.

package.json

{
    "keycloakify": {
        "bundler": "none"
    }
}

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:

KEYCLOAKIFY_BUNDLER=none npx keycloakify

keycloakify.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

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 package.json["name"]-keycloak-theme

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.

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_VERSION="4.5.6" npx keycloakify

The version also affects the name of the .jar file.