Contributing

Dev setup

bash

git clone https://github.com/kathari00/keycloak-theme-editor.git
cd keycloak-theme-editor
npm ci
npm run dev

Open the URL it prints (defaults to http://localhost:5173).

Requirements

Node.js 24, to match CI; the package itself only requires 20.19.0 or newer.
JDK 17 and Maven, to match CI, for building the renderer and regenerating previews.
Docker, for the real-Keycloak integration tests.

Scripts

Command	Description
`npm run dev`	Dev server
`npm run build`	Type-check + production build
`npm run build:cli`	Build the CLI bundle
`npm run build:jar`	Build the Java preview renderer JAR
`npm run test:run`	Run tests once
`npm run lint`	ESLint
`npm run sync:keycloak`	Sync upstream Keycloak templates into `public/keycloak-upstream/`
`npm run generate:preview`	Regenerate preview `pages.json`
`npm run generate:preview -- --locales=all`	Regenerate every curated language
`npm run vendor:check`	Check adapted theme files against synced upstream content
`npm run vendor:apply`	Apply the stored theme adaptations
`npm run generate:carbon`	Rebuild the checked-in Carbon CSS and embedded fonts
`npm run test:e2e`	Run the editor's Playwright suite in Chromium
`npm run test:keycloak-integration`	Test an exported theme against real Keycloak, via Docker

How the codebase is organized

src/
  app/              # Editor shell and wiring
  components/       # Sidebar, topbar, panels
  features/
    assets/         # Upload and asset management
    editor/         # CSS editing, undo/redo, style layers
    presets/        # Preset selection logic
    preview/        # Iframe preview and generated artifacts
    theme-document/ # Canonical theme state used by preview and export
    i18n/           # Supported locale catalog
    theme-export/   # JAR/folder export and import

public/
  keycloak-dev-resources/   # Base theme resources

bin/
  cli.ts            # CLI entry point

tools/
  sync-keycloak.ts      # Upstream template sync
  theme-adaptations/    # Adaptation rules, patches, and update runbook
  preview-renderer/     # Java-based preview generation

Before you open a PR

Run npm run lint, npm run test:run, and npm run build. If you touched anything browser-facing, install Chromium once (npx playwright install chromium) and run npm run test:e2e. Changed the export pipeline or a template? Also run npm run test:keycloak-integration (needs Docker).

Changing adaptation rules? Sync the pinned upstream release first, then run vendor:check. Intentionally updating Keycloak itself? Follow the update runbook and commit the pin, patches, and generated output together.

Editing these docs

This site lives in a separate repo, keycloak-theme-editor-docs. Clone it, npm ci, npm run dev. Run npm run build before committing: VitePress checks internal links at build time and will catch a broken one.

Contributing ​

Dev setup ​

Requirements ​

Scripts ​

How the codebase is organized ​

Before you open a PR ​