Building a React-based Keycloak theme and i18n with Keycloakify

While introducing Keycloak to the Autowini service, I customized the login screen. There were few resources on this in Korean, so I'm sharing what I went through during implementation and how I finished support for 15 languages with Keycloakify.

Why Keycloakify

Keycloak login screens use FTL (FreeMarker Template Language) syntax by default. With future maintenance of the project in mind, though, I chose the Keycloakify framework.

The biggest reason was that we could keep using React (JSX) syntax, which the team already knew. It would reduce the learning curve and let us use the libraries we were already using, so I judged it better for development productivity.

1. Theme branching per client (clientId)

Within a single project, I used clientId as the identifier to branch the UI between administrators (Admin) and regular users (Web).

• Admin (autowini-admin): I applied a compact, 300px-wide dark theme UI.
• Service web (autowini-web): I applied a 360px-wide light theme with a Floating Label animation. (When the user is redirected from a product detail page, it detects that and shows a 'membership info box'.)

2. 15-language (i18n) support and troubleshooting

Autowini has to support 15 languages, but some parts were hard to handle with Keycloakify's built-in system alone.

The problems:

1. Unsupported languages: Some languages, such as az, sw, km, my, and mn, were not included in Keycloakify's default library.
2. Language setting reset: When login failed, the page reloaded and the ui_locales parameter in the URL was lost, so the language went back to English (en).

Solution: Instead of the built-in system, I set up i18next separately and used SessionStorage. I saved the language code read from the URL to the session, so the language the user chose stays after a reload.

https://youtu.be/78PTPE5I6I4

3. Using Storybook

I already knew Storybook existed, but I didn't feel much need to bring it into actual development. On this project, though, I experienced its usefulness firsthand.

I forked the Keycloakify project and made active use of its built-in Storybook setup. Being able to check many cases right away, without editing code or changing state values by hand each time, was very convenient.

In particular, I could immediately simulate specific scenarios, such as error messages or the re-authentication flow, without running a Keycloak server myself, and that sped up development a lot. Setting up the environment at the start can be a bit of a hassle, but I learned that once it is in place, it helps a lot in cutting debugging time and raising the overall quality.

Looking back

The key part of this work was that, as the Keycloak authentication system was being introduced, the frontend team took part starting from login page development and decided on the best way to implement it.

At first we considered using the default FTL (FreeMarker Template Language) syntax, but after some R&D we decided to adopt Keycloakify. That let us use the React syntax we knew and made development much more efficient.

At first I also planned to manage the admin and web projects separately, but with operational efficiency and maintainability in mind, I designed it as a structure managed within a single project. Thanks to that, we could share common components and business logic efficiently and keep the setup extensible.

There were few resources in Korean, which made the build difficult at times, but in the end I built a stable authentication system with the combination of Keycloakify and React.

If you have questions about the implementation or the detailed logic, leave a comment. I'll answer in detail as far as I know.