Difference between the 'extend-account-console' and 'extend-account-console-node' quickstarts #38739

DevDuki · 2025-04-08T09:36:03Z

DevDuki
Apr 8, 2025

Hi, as the title says, I am unsure what the differences between the two quickstarts extend-account-console and extend-account-console-node are.

Which one am I supposed to use if I, for example want to edit an existing page like the Signing In page?

Are both still relevant?

I know that for the extend-account-console-node quickstart there is an npm tool which basically generates that same quickstart extension for you via the npm create keycloak-theme@latest my-theme command. Is there one for the extend-account-console too?

How to know which one I should favour over the other based on use cases?

Thanks in advance for any clarifications!

edewit · 2025-04-09T08:08:52Z

edewit
Apr 9, 2025
Collaborator

extend-account-console is a quickstart that lets you add and or remove pages from the account console. It accomplish this by editing the content.json file that is used to create the routes. It also shows how to customize the look and feel by overriding the patternfly styles.
extend-account-console-node on the other hand uses the components of the account console to build a new account console from "scratch". This is way more flexible and you can do anything you like, also shows how to re-use different parts.

So yeah they are both relevant as they show different types of extending, if you only want to remove a page or add one that is very simple. I would suggest to use the content.json. But if you need more control and you are not scared of building some pages with React then use the component library.

I know that for the extend-account-console-node quickstart there is an npm tool which basically generates that same quickstart extension for you via the npm create keycloak-theme@latest my-theme command.

Right if you choose to build it, this would be the best starting point, as the keycloak-theme tool will add naming to the created project.

Is there one for the extend-account-console too?

There is not, because this is a much simpler way to extend the console and the quickstart is more of an example of what is possible then an actual starting point

Hope this answers your questions

2 replies

DevDuki Apr 10, 2025
Author

Ah I see. Thank you for your explanation!

I have been tinkering with both the extension since last week and I also came to the conclusion that the extend-account-console-node extension basically makes you build the entire app from scratch, while in the extend-account-console you can just pick what's new for you and the rest is reused by keycloak.v3.

Now I have a small suggestion/improvement/bugfix that I need you guys' opinion on. It has something to do with this comment I made in the keycloak-quickstarts repo.

Little intro:
For a customer I have to make a teeny tiny feature change in the SigningInPage.tsx file. Now I tried to implement this change in the extend-account-console-node way with the npm create keycloak-theme@latest my-theme tool. I noticed I had to fix quite a few other things around it, which had nothing to do with my feature (will list them later to keep the intro short). I am suddenly also responsible for the routing, translations, etc. which I don't really want to change and keep it the same way as it is in the keycloak.v3 theme. The fixes and the new responsibilities have forced me to copy a lot of other source code from the keycloak repo, which in the future, when you guys make new releases, all have to be maintained manually. This is very suboptimal and way too invasive to the default keycloak.v3 theme.

I then noticed the extend-account-console way, which gave me the impression that I could just re-implement the SigningIn.tsx Page myself (including all its imports/dependencies), point it to the content/signing-in path in content.json with the modulePath property pointing to my built SigningIn.js file. This on the other hand doesn't work with the current keycloak.v3 react codebase. In fact not even the keycloak-man example works at the moment (see this issue for more information). However, if this would work as intended, this would be a much cleaner way of implementing my change, because then I only have to maintain my own SigningIn.tsx file and perhaps some of its imports that aren't made available by the @keycloak/keycloak-account-ui package (e.g. the util functions, i18n, etc.). I would be totally ok with this.

My suggestion/Improvement:
Basically what I suggested in the comment I mentioned in the beginning. This would make it possible to override any page we like and even keep it in the same path as its original page was. It would also make the ContentComponent.tsx obsolete and only the <Component modulePath={string} component that is inside ContentComponent.tsx would be necessary. Furthermore the dynamic content route content/:componentId in routes.tsx would be unnecessary too then (which right now has no use anyway, because the mapRoutes function defined in Root.tsx does not even take it into consideration).

Bugs:
Both extension are quite buggy at the current state. I already opened some issues to them.

For the extend-account-console-node:

#676 in the quickstart repo.

For the extend-account-console:

#678 in the quickstart repo. The one I mentioned in my intro, which contains my suggestion. Perhaps should be moved to this repo as well, as the fix has to be done in the account-ui module.

Affects both:

I would be happy to help fix some of the issue when I find some time, however I still haven't figured out why this one #676 is happening. Because the toggle works as intended when using the default keycloak.v3 theme.

Outro:
So what do you think of my suggestion with the modulePath in the mapRoutes function? Does this meet your expectations of what the content.json should be capable of? Maybe it is worth mentioning that I couldn't find any documentation regarding how to use the content.json, what it's for and what possibilities/options it provides. Perhaps this can be improved a little as well.

DevDuki Apr 10, 2025
Author

I added 2 new example extensions in my quickstarts fork to demonstrate what I had to do in order to get the extensions to run properly (except for "not-node" extension, that one won't work and can't be tested until this issue is fixed).

My goal was to add a change to the SigningIn.tsx page (for demo purpose I just added a <h1>{t("hello")}</h1> line in the render function). My example extensions are called extend-account-console-node-signing-in and extend-account-conole-signing-in.

The "node" extension contains all the workarounds I had to implement in order for the app to work smoothly (see issues I mentioned in my previous reply). Perhaps it would look a lot smaller when those issues were fixed.

The "not-node" extension only contains the changes I think would be necessary for the new SigningIn.tsx page to replace the old one. It also assumes that my suggestion was implemented and uses the modulePath for the account-security/signing-in route in content.json.

Hope that helps understanding where I am coming from and what I am trying to achieve.

ssilvert · 2025-04-09T19:01:07Z

ssilvert
Apr 9, 2025
Collaborator

@DevDuki extend-account-console is an older way to do account console customization. It still works and the techniques described may be simpler for some situations.

extend-account-console-node provides a template that can be used for full customization down to the React source code level. If you need that level of control I would suggest looking at the create-keycloak-theme tool. It will basically just generate what you see in extend-account-console-node without the need to clone the quickstarts repo.

pnpm install -g create-keycloak-theme
pnpm create keycloak-theme my-theme -t account

0 replies

Navigation Menu

Repository navigation

Difference between the 'extend-account-console' and 'extend-account-console-node' quickstarts #38739

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Difference between the 'extend-account-console' and 'extend-account-console-node' quickstarts #38739

Uh oh!

DevDuki Apr 8, 2025

Replies: 2 comments · 2 replies

Uh oh!

edewit Apr 9, 2025 Collaborator

Uh oh!

Uh oh!

DevDuki Apr 10, 2025 Author

Uh oh!

Uh oh!

DevDuki Apr 10, 2025 Author

Uh oh!

ssilvert Apr 9, 2025 Collaborator

DevDuki
Apr 8, 2025

Replies: 2 comments 2 replies

edewit
Apr 9, 2025
Collaborator

DevDuki Apr 10, 2025
Author

DevDuki Apr 10, 2025
Author

ssilvert
Apr 9, 2025
Collaborator