package-manager-workspaces.md

Package Manager Workspaces

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

{% tabs %} {% tab title="yarn/npm/bun" %}

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

{% endtab %}

{% tab title="pnpm" %} {% code title="pnpm-workspace.yaml" %}

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

{% endcode %} {% endtab %} {% endtabs %}

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.

{% code title="apps/keycloak-theme/package.json" %}

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

{% endcode %}

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

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:

{% tabs %} {% tab title="pnpm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="npm" %}

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

{% endtab %}

{% tab title="bun" %}

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

{% endtab %} {% endtabs %}

Now you can run:

{% tabs %} {% tab title="pnpm" %}

pnpm install
pnpm run build-keycloak-theme

{% endtab %}

{% tab title="yarn" %}

yarn
yarn build-keycloak-theme

{% endtab %}

{% tab title="npm" %}

npm install
npm run build-keycloak-theme

{% endtab %}

{% tab title="bun" %}

bun install
bun run build-keycloak-theme

{% endtab %} {% endtabs %}

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.

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.