Nx Integrated Monorepo

Before You Start:

This documentation section is intended for cases where you already have an existing project and want to add a Keycloak theme as part of its deliverables.

One of Keycloakify’s strengths is its ability to let you reuse components and styles from your main application in your Keycloak theme. However, if you don’t have an existing codebase, it’s easier to and develop your Keycloak theme as a standalone project.

Let's see how to integrate a Keycloakify theme into a Nx project with integrated monorepo.

In this example we'll start with the Nx Vite starter

npx create-nx-workspace@latest --preset=react-monorepo --bundler=vite

Next up we want to repatriate the Keycloakify Starter template sources. We only copy over the src and .storybook directory.

cd nx-monorepo
rm -rf apps/keycloak-theme/src
git clone https://github.com/keycloakify/keycloakify-starter tmp
mv tmp/src apps/keycloak-theme
mv tmp/.storybook apps/keycloak-theme
rm -rf tmp

After moving src and .storybook to apps/keycloak-theme

package.json

{
  "name": "@nx-monorepo/source",
  "version": "0.0.0",
  "scripts": {
    "build-keycloak-theme": "nx build keycloak-theme && keycloakify build -p apps/keycloak-theme",
    "keycloak-theme-storybook": "npx storybook dev -p 6006 -c apps/keycloak-theme/.storybook",
    "start-keycloak": "keycloakify start-keycloak -p apps/keycloak-theme"
  },
  "dependencies": {
    "react": "18.3.1",
    "react-dom": "18.3.1",
    "tslib": "^2.3.0",
    "keycloakify": "^10.0.0"
  },
  "devDependencies": {
      "storybook": "^8.1.10",
      "@storybook/react": "^8.1.10",
      "@storybook/react-vite": "^8.1.10"
  // ...

npm install # or `pnpm install` or `yarn`...

apps/keycloak-theme/vite.config.ts

/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { keycloakify } from "keycloakify/vite-plugin";

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/apps/keycloak-theme',

  server: {
    port: 4200,
    host: 'localhost',
  },

  preview: {
    port: 4300,
    host: 'localhost',
  },

  plugins: [react(), nxViteTsPaths(), 
      keycloakify({
          themeName: "my-project",
          themeVersion: "1.0.0",
          keycloakifyBuildDirPath: '../../dist/apps/keycloak-theme'
       })
   ],

  // Uncomment this if you are using workers.
  // worker: {
  //  plugins: [ nxViteTsPaths() ],
  // },

  build: {
    outDir: 'dist',
    emptyOutDir: true,
    reportCompressedSize: true,
    commonjsOptions: {
      transformMixedEsModules: true,
    },
  },
});

Now if you run npm run build-keycloak-theme it will generate the JAR 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

OR

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

To go beyond the base configuration you might want to explore what build options are available. Starting with with keycloakVersionTargets to make sure that you only generates the JARs file you need.