Feature: allow the built-in login page to be replaced from the custom directory

[shuans]

Summary

Please allow the built-in login page to be replaced by a custom Vue component from the custom/ directory, the same way customization.customPages lets you add pages.

Current behavior

/login is hardcoded in the SPA router (spa/src/router/index.ts) and points at @/views/LoginView.vue. No configuration option changes it. The only login-page extension points are loginPageInjections (panelHeader / underInputs / underLoginButton), loginBackgroundImage, loginBackgroundPosition, loginPromptHTML and demoCredentials — all of which add to the built-in page rather than replacing it.

Adding a customPages entry with path: '/login' does not work. I checked why, against 3.29.0 and vue-router 4.3.0 / 4.5.1 / 4.6.4 — there are four independent blockers:

1. customPages routes are emitted at the /* IMPORTANT:ADMINFORTH ROUTES */ placeholder in spa/src/router/index.ts, which sits after the built-in routes. The built-in /login is therefore registered first.
2. vue-router 4 keeps the first matcher for a duplicate path. resolve('/login') returns the built-in component and the custom one is unreachable — I verified this on all three vue-router versions above, with the routes in both orders.
3. Redirects target the route name: router.push({ name: 'login' }) in App.vue and in spa/src/utils/utils.ts. registerCustomPages names a custom page name: '<path>', i.e. '/login', so name: 'login' never matches it.
4. There is no config key for a login component.

Why this matters

The login page is the first screen every user sees and the one teams most often want to restructure: split/centered layouts, tenant or workspace selection, SSO and passkey buttons, a language switcher, custom copy, marketing or legal panels next to the form. loginPageInjections covers three insertion points, so anything structural — replacing the heading and the inputs, two-column layouts, a different field order — is out of reach.

The only alternative today is patching AdminForth's own spa/src/views/LoginView.vue and spa/src/router/index.ts. That is exactly the maintenance burden teams try to avoid: the patch is keyed to an exact package version, so it silently stops applying on the next release, and the failure mode is a login page that quietly reverts to the stock one.

Custom pages already prove the mechanism works. The login page is the notable exception.

Proposed API

Any of these would solve it. The first is the smallest:

customization: {
  // a component in ./custom that replaces views/LoginView.vue
  loginPage: '@@/MyLogin.vue',
}

or a customPages-shaped declaration, so meta comes along:

customization: {
  loginPage: {
    component: { file: '@@/MyLogin.vue', meta: { sidebarAndHeader: 'none' } },
  },
}

Requirements:

• when unset, behaviour is unchanged;
• the route keeps path: '/login' and name: 'login', so every router.push({ name: 'login' }), the existing beforeEnter guard and the 401 redirect keep working;
• no new plumbing needed — custom/ is already aliased to @@ and copied into the SPA sources, so this can reuse whatever customPages uses to emit component: () => import('...');
• please document the contract a custom login page has to implement (at minimum POST /login with { username, password, rememberMe } and what to do with the response), or export the built-in LoginView.vue so it can be wrapped and extended instead of reimplemented from scratch — the latter would make this far less risky for anyone who still wants the stock flow plus their own layout;
• keep loginPageInjections, loginBackgroundImage, loginBackgroundPosition and loginPromptHTML working, so projects that only need the small hooks are unaffected.

Workaround today

Patching the route in spa/src/router/index.ts:

-      component: () => import('@/views/LoginView.vue'),
+      component: () => import('@@/MyLogin.vue'),

This does work — same path, same name: 'login', and @@ resolves to src/custom via the vite alias in spa/vite.config.ts. But it is a patch against the installed package, which is the whole problem.

[ivictbor]

What I don't like about it such concept that when developer (or his low-tier LLM like sonnet/terra) is hard-forking the template he takes full responsibility on inputs crafting, e.g. developer might screw up with type attributes or input autocompletion attributes and it will brake compatibility with password managers or they might forget to place templates for injection and break all plugins, and standard page polished this. Or they will forget about overflow which might happen due to login page injections and new plugins installation for Oauth/PassKey will look like a piece of x and adminforth bug, and user will then blame adminforth - but actually he did hardfork, his llm forgot about that cases that we solved on standard page

So we knew about such demand as fully customize login page - but by design the concept was - we allow some injections for different areas - if demand is missing e.g. to have injection for image or some side area or something else - let us know.

the one teams most often want to restructure:
Most of such tasks does not require hardforking full html layout can can be done with css and we support it - declary global styles hook on components and use flex, order,direction - you can do so many things about it

split/centered layouts

Definitely sounds CSS task but you can send screenshot and we will maybe came up with something

tenant or workspace selection

This is just injection - why not using this https://adminforth.dev/docs/tutorial/Customization/pageInjections/#login-page-customization ? If you need to pass the workspace id with login API - it is possible

SSO and passkey buttons

So it is already implemented by plugins https://adminforth.dev/docs/tutorial/Plugins/oauth/ and for login with PassKey https://adminforth.dev/docs/tutorial/Plugins/two-factors-auth/

These plugins have a ton of well-polished secure code, with hundreds of hours after real cross-platform cross-browser user feedbacks and real strong audits reports, and if you wish to recreate it from scratch - well - this is possible but it is like significant part of framework where we give a lot value which should save you a lot of time per quality. I mean we do it for ourselves and share with world and we ensure tight security and strong standards compliance.

About workspace id on login page:

In general concept to use workspace ID on login phase most likely will kill a lot of adminforth plugins to work because it simply searches user by username/email and then checks password. You will end-up writing all custom APIs for login and reimplementing plugins and again you take a lot of extra security and responsibility which we already manage for developers who use those pass from adminforth. We support that security layer with time.

Moreover and more important - this concept is often is a hell for users. When it used e.g. in AWS - it is strongly criticized because for any user it is not typical to have on login form username+password+3rd input for workspace. Again it brakes standards, it does not allow to use password managers (they simply cant remember this 3rd field) so it brakes them, makes insecure because instead of nice strong passwords user have to manage this hell in some other ways copy paste somewhere ahhr... even AWS now moving to workspace switch after login if you seen it... And is moving right. What is good and user-friendly tech companies do - they have one user object for all workspaces and simply link him with many workspaces, so dropdown is already inside the app - so user still signs in with user+password/Webauthn/email OTP/ whatever - and then he has workspace dropdown inside, maybe prefilled with last used workspace. This concept makes everything clear and understandable. AWS did such login because of splitting accounts between workers and distributing load - when they know workspace id early they can select node and select database to search login and password. This is cool and clear for high-load developers but it is ux catastrophe. Slack has same thing with workspace selection - it created so significant hell for users - yes they did it for multi-node horizontal scaling architecture - and they created so many pain for those staff like you have account in every workspace, then they created crunches for that "find my workspace", paid slack connect and so on, this is so user-kidding (real feedbacks from reddit exist).

They key thing - node-fitting is also not an issue - this is possible to master it our with one centralized service for credentials and workspace mapping and further proxying to worker nodes. This is a best approach.

The bottom line if you really care about your users:

One person in this world on one website should have one account and one credentials or factors setup (99% cases, I doubt u are under that 1%). Which is standard way to login to any web resource. No extra inputs. And this is it. Workspace is linked after login and this is internal stuff. Then user will not have manage a lot of credentials for one website, will not risk their leaking and will be able to login easily

[ivictbor]

@yaroslav8765 I assume you've already implemented this, so we can keep it, but we should probably add a notice in the docs explaining that this approach is not recommended for layout or styling changes because it shifts responsibility for maintaining the login UI's security-sensitive behavior, password-manager compatibility, and plugin integration to the application developer.

Something like this:

Warning: Replacing the login template requires ongoing maintenance.

Prefer CSS customization and login-page injections over replacing the entire login template. These extension points let you customize the page while retaining the behavior and compatibility maintained by AdminForth.

When replacing the template, you are responsible for preserving the correct form field types and autocomplete attributes, required plugin injection points, and layouts that accommodate additional authentication methods. Missing or modified elements can interfere with password managers, prevent authentication plugins from working correctly, or cause layout issues when new plugins are installed.

Your custom template will not automatically inherit security-related fixes, compatibility improvements, or new integration points added to the default template. You must review and incorporate relevant changes when upgrading AdminForth.

If the existing injection points do not cover your use case, please open an issue describing the customization you need before maintaining a separate login template.