In your Vite Project
If you have a Vite/React/TypeScript project you can integrate Keycloakify directly inside it.
In this guide we're going to work with a vanilla Vite project.
![](https://docs.keycloakify.dev/~gitbook/image?url=https%3A%2F%2F723341942-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1pGOu8uVH5l8KqPEPmKi%252Fuploads%252FweXSYedBuNqNLhf79Zqg%252Fimage.png%3Falt%3Dmedia%26token%3Da468c6c0-df3f-4927-b463-ec8c7f2dd20c&width=768&dpr=4&quality=100&sign=3c94a26c&sv=1)
![](https://docs.keycloakify.dev/~gitbook/image?url=https%3A%2F%2F723341942-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1pGOu8uVH5l8KqPEPmKi%252Fuploads%252FXN3o60cy7pYsbheV77cz%252Fimage.png%3Falt%3Dmedia%26token%3Da967bab6-2d8e-41d3-8a7a-77bb8dbf6741&width=768&dpr=4&quality=100&sign=f7c6b2a6&sv=1)
Before anything make sure to commit all your pending changes so you can easily revert changes if need be.
Let's start by installing Keycloakify (and optionally Storybook) to our project:
Next we want to repatriate the relevent files from the starter template into our project:
![](https://docs.keycloakify.dev/~gitbook/image?url=https%3A%2F%2F723341942-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F1pGOu8uVH5l8KqPEPmKi%252Fuploads%252FnPJLH9vwMAcwThEzzJ5Y%252Fafter_import.png%3Falt%3Dmedia%26token%3D30ebb939-27dc-49de-9b7e-1e49e24e584d&width=768&dpr=4&quality=100&sign=b74c5379&sv=1)
Now you want to modify your entry point so that:
If the kcContext global is defined, render your Keycloakify theme
Else, reder your App as usual.
Question:
Why do my main application and Keycloak theme share the same entry point?
Answer:
To simplify the build process. If you don't want it to negatively impact the performance of your application, it's essential to understand the following points:
Different Contexts: The application (
App
) and Keycloak page (KcPage
) are mounted in very different contexts. Avoid sharing providers between the two at themain.tsx
file level. The true entry point of your application is theApp
component, while the entry point for your Keycloak theme is theKcPage
component. Be careful about what code is shared between them.Responsibility of main.tsx: The
main.tsx
file should only determine the context (either the application or Keycloak) and mount the appropriate component (App
orKcPage
). It should not contain any substantial logic or dependencies.Performance Considerations: Keep
main.tsx
as lightweight as possible to avoid increasing the initial load time of both your main application and login pages. For example, do not load any state management libraries likeredux-toolkit
at this level.
You also need to use Keycloakify's Vite plugin. Here we don't provide any build options but you probably at least want to define keycloakVersionTargets.
Leave accountThemeImplementation set to "none" for now. To initialize the account theme refer to this guide.
Finally you want to add to your package.json a script for building the theme and another one to start storybook.
That's it, your project is ready to go!
You can run npm run build-keycloak-theme, the JAR distribution of your Keycloak theme will be generated in dist_keycloak.
You're now able to use all the Keycloakify commands (npx keycloakify --help
) from the root of your project.
If you're currently using keycloak-js or react-oidc-context to manage user authentication in your app you might want to checkout oidc-spa, the alternative from the Keycloakify team.
If you have any issues reach out on Discord! We're here to help!
Last updated