Сегодня хочу рассказать, как спокойно начать проект на Keycloakify для создания темы для Keycloak. Версия первого — 11.8.24, а второго — 26 соответственно.
Если останутся вопросы по каким-то моментам, идем в документацию. Там можно найти ответы на все оставшиеся вопросы, а также узнать, какие страницы поддерживаются Keycloakify по умолчанию.
Создание проекта
Итак, создаем новый репозиторий, клонируем в него шаблон Keycloakify и устанавливаем зависимости (чтобы избежать проблем, берем ссылку на clone из документации — не стоит искать шаблон Keycloakify в интернете и т.д)
git clone https://github.com/keycloakify/keycloakify-starter .
yarn
Далее есть два варианта разработки:
-
Разрабатывать страницы через Storybook без локального Keycloak.
-
Запускать Keycloakify с локальным поднятым Keycloak.
1. Разработка через Storybook
Выполняем команду и запускаем Storybook:
npx keycloakify add-story
yarn storybook
2. Разработка с локальным Keycloak
Добавляем в package.json команду с нужной версией Keycloak и запускаем:
"dev-in-docker": "NODE_ENV=development && keycloakify start-keycloak --keycloak-version 26.2.0"
yarn dev-in-docker
Логин-тема
Чтобы отредактировать логин-тему, нужно выполнить eject нужных страниц:
npx keycloakify eject-page
Далее остается:
-
Отредактировать компонент Template под свои нужды или написать свою личную обертку для страниц.
-
Изменить страницы логина, регистрации и т. д. в соответствии с дизайн-макетами.
Аккаунт-тема
Для редактирования аккаунт-темы запускаем команду и выбираем один из вариантов:
npx keycloakify initialize-account-theme
-
single-page (напоминает React-приложение, лучше поддерживает новые фичи Keycloak).
-
multi-page (работает аналогично логин-теме, с eject страниц и последующей их модификацией).
Разница между single-page и multi-page
-
Multi-page: работаем со страницами так же, как в логин-теме и сделан на основе первых версий Keycloak.
-
Single-page: придется повозиться побольше. Придется вручную запускать команду(можно увидеть нижу) для того, чтобы Keycloakify понял для себя, что данный файл стал модифицируемым и не изменял его при каждой установке зависимостей.
Чтобы защитить изменения, выполняем для каждого файла команду:
npx keycloakify own --path "path-to-file + file-name"
Если этого не делать, при переустановке зависимостей все вернется к настройкам по умолчанию.
Если не хочется следить за этим: можно убрать файлы из .gitignore в /src и удалить команду postinstall из package.json, чтобы избежать случайного сброса при установке зависимостей.
Переводы
Для логин-темы и multi-page аккаунт-темы
В i18n.ts добавляем вызов withCustomTranslations и передаем объект с переводами.
Для single-page аккаунт-темы
Нужно:
-
Найти файл с нужной локалью и убрать его из .gitignore при помощи волшебной команды npx keycloakify own --path.
-
Создать файл с суффиксом overrides и добавлять туда кастомные переводы под требуемую для нас локаль.
Сборка под разные версии
Чтобы создать .jar с определенным названием и версией, в vite.config передаем нужные параметры в функцию keycloakify:
Заключение
Когда я впервые начал работать с Keycloak и Keycloakify, это показалось неудобным. Но на самом деле дело там обстоит не так уж и плохо и лично для себя хочу оставить напоминание: внимательно читай документацию перед началом работы!
Вот ссылка на нее: https://docs.keycloakify.dev/
