yarn/npm/pnpm/bun Workspaces

If you're unsure what this section is about, this approach is NOT for you. Instead, follow the Quick Start Guide and fork the starter project.

Let's assume we have a monorepo project where sub applications are stored in the apps/ directory.

yarn/npm/bun

package.json

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

pnpm

pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

Then, you want to create a new app called, for example 'keycloak-theme' and initialize it with the code of the starter template:

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

Now you want to update the name field of your apps/keycloak-theme/package.json to match the name of your sub app.

apps/keycloak-theme/package.json

 {
-    "name": "keycloakify-starter",
+    "name": "keycloak-theme",

You also want to provide an actual name to your theme as you want it to appear in the Keycloak Admin UI.

apps/keycloak-theme/vite.config.ts

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({
        themeName: "my-app"
    })]
});

Now you can add a script in your root package json to build the theme and start the keycloak dev server:

pnpm

package.json

{
   "name": "my-monorepo",
   "scripts": {
       "build-keycloak-theme": "pnpm --filter keycloak-theme run build-keycloak-theme",
       "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
   },
   // ...
}

yarn

package.json

{
   "name": "my-monorepo",
   "scripts": {
       "build-keycloak-theme": "yarn workspace keycloak-theme run build-keycloak-theme",
       "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
   },
   // ...
}

npm

package.json

{
   "name": "my-monorepo",
   "scripts": {
       "build-keycloak-theme": "npm run build-keycloak-theme --workspace=keycloak-theme",
       "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
   },
   // ...
}

bun

package.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"
   },
   // ...
}

Now you can run:

pnpm

pnpm install
pnpm run build-keycloak-theme

yarn

yarn
yarn build-keycloak-theme

npm

npm install
npm run build-keycloak-theme

bun

bun install
bun run build-keycloak-theme

Two common thing you might want to do is change the location of the directory where the JARs files are generated and only build the JAR for the Keycloak version you are using.

apps/keycloak-theme/vite.config.ts

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({
        themeName: "my-app",
        keycloakifyBuildDirPath: "../../dist/apps/keycloak-theme",
        keycloakVersionTargets: {
            hasAccountTheme: true,
            "21-and-below": false,
            "23": false,
            "24": false,
            "25-and-above": "keycloak-theme.jar"
        }
    })]
});

In this configuration when you run pnpm run build-keycloak-theme from the root of your monorepo a single keycloak-theme.jar will be generated in dist/apps/keycloak-theme:

When you want to use the keycloakify CLI commands you can either cd into your keycloakify sub app directory or use the --project option of the Keycloakify CLI. Like for example if you want to run add-story you can do either:

• cd apps/keycloak-theme && npx keycloakify add-story

• npx keycloakify add-story -p apps/keycloak-theme from the root of your monorepo.