Outside of Keycloak

The recommended way to preview your theme as you develop it is to use Storybook. Storybook is a tool that enables to test UI component in isolation. For reference the following website was generated with storybook:

Keycloakify Storybook

If you prefer to avoid intoducing Storybook into your stack, it's okay, you can still preview your page in dev mode. Do do so, refer to this guide.

The starter template does not initially contain any story files, instead there's a keycloakify CLI command that let's you import specifically the stories for the pages you want to test into your project.

So, just run this command in the root of your Keycloakify project and select the pages you want.

npx keycloakify add-story

It will enables you to select the pages you want to add stories for.

Selecting login -> register.ftl will result in this file to be created in your project:

You can run the above command multiple times to add stories for the different pages you want to develop.

Once your added a few stories you can start Storybook locally with:

npm run storybook

You can see the changes you make in you code in realtime in your Storybook.

The idea of Storybook is to easily let you see the pages in different configuration without having to reproduce the full login/register process in a real Keycloak. Keycloakify provide a default mock context for every pages, the stories let you partially override some specific part of this default mock to reflect pages in different configurations. For example, if you want to create a story that show the register page in chinese you would add this:

React

src/login/pages/Register.stories.tsx

import type { Meta, StoryObj } from "@storybook/react";
import { createKcPageStory } from "../KcPageStory";

const { KcPageStory } = createKcPageStory({ pageId: "register.ftl" });

const meta = {
    title: "login/register.ftl",
    component: KcPageStory
} satisfies Meta<typeof KcPageStory>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {
    render: () => <KcPageStory />
};

export const InChinese: Story = {
    render: ()=> (
        <KcPageStory
            kcContext={{
                locale: {
                    currentLanguageTag: "zh-CN"
                }
            }}
        />
    )
};

Angular

src/login/pages/register/register.stories.ts

import { Meta, StoryObj } from '@storybook/angular';
import { decorators, KcPageStory } from '../KcPageStory';
import { Attribute } from 'keycloakify/login';

const meta: Meta<KcPageStory> = {
    title: 'login/register.ftl',
    component: KcPageStory,
    decorators: decorators,
    globals: {
        pageId: 'register.ftl'
    }
};

export default meta;

type Story = StoryObj<KcPageStory>;

export const Default: Story = {};

export const InChinese: Story = {
    globals: {
        kcContext: {
            locale: {
                    currentLanguageTag: "zh-CN"
            }
        }
    }
};

Svelte

src/login/pages/Login.stories.svelte

<script
  context="module"
  lang="ts"
>
  import { defineMeta } from '@storybook/addon-svelte-csf';
  import type { KcPageStoryProps } from '../KcPageStory';
  import KcPageStory from '../KcPageStory.svelte';

  const args: KcPageStoryProps = { pageId: 'login.ftl' };
  const { Story } = defineMeta({
    title: 'login/login.ftl',
    component: KcPageStory,
    args: args,
  });
</script>

<Story name="Default" />

<Story
  name="InChinese"
  args={{
    ...args,
    kcContext: {
      locale: {
        currentLanguageTag: "zh-CN"
      }
    }
  }}
/>

Now let's see how to test our theme in a real Keycloak instance:

Inside of Keycloak