Package Manager Workspaces

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

package.json

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

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:

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

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

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

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 install
pnpm run build-keycloak-theme

yarn
yarn build-keycloak-theme

npm install
npm run build-keycloak-theme

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.

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

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

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

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

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" } })] });