Frontend

Server-rendered BXM views, small Alpine.js components, and a Vite-compiled SCSS/JS pipeline.

Frontend

How it fits together

The frontend is a hybrid server-rendered + Alpine.js application - no SPA, no client-side router:

Alpine.js architecture

App.js (entry)
  ├── Registers all Alpine stores + components
  ├── Imports Bootstrap JS + Phosphor icons + Tippy.js
  │
  ├── Stores ($store.*)
  │   ├── theme.js     → dark/light mode, syncs data-bs-theme + localStorage
  │   └── sidebar.js   → collapse/open, mobile overlay, localStorage persistence
  │
  └── Components (x-data)
      ├── auth/        → AuthForm, RegisterForm, ForgotPasswordForm, PasswordResetForm
    ├── security/     → AuditLogForm, PermissionsForm, RolesForm, UserDetailForm, UsersForm
    ├── profile/      → PasskeyOnboarding, PreferencesForm, ProfileForm
    ├── settings/     → SettingsForm, SettingsRegistryForm
    └── ui/           → Drawer, GlobalProgress, GlobalToast, Logo, MessageBox, PasswordMeter, PasswordStrength, Switch

Each component is a standalone module returning an Alpine x-data object:

export default () => ( {
    visible: true,
    init() {
        setTimeout( () => this.visible = false, 5000 );
    }
} );

<div x-data="messageBox" x-show="visible" x-transition>
    <!-- alert content -->
</div>

SCSS structure

app.scss
  ├── _variables.scss   Bootstrap variable overrides
  ├── bootstrap          Full Bootstrap 5.3 import
  ├── _base.scss         CSS custom properties (light/dark theme)
  ├── components/        9 component partials
  ├── layouts/            Admin + Auth layout partials
  └── views/              Page-specific styles

Vite configuration

vite.config.mjs uses coldbox-vite-plugin's coldbox() plugin:

• Entry points: resources/assets/scss/app.scss and resources/assets/js/App.js
• refresh: appRefreshPaths — auto full-reload on handler/view changes
• publicDirectory: "public/includes" — where built assets land
• SCSS preprocessor with silenceDeprecations flags for newer Dart Sass (import, global-builtin, color-functions, if-function)

npm run dev        # Vite dev server with HMR
npm run build      # Production build → public/includes/
npm run lint       # ESLint check on resources/assets/js
npm run lint:fix   # ESLint auto-fix
npm run lint:scss  # Stylelint on resources/assets/scss

Server-rendered view components

These BXM partials live under app/views/_components/ and are rendered with ColdBox's view() helper. They are intentionally presentation-focused: pass values through the args struct and keep business logic in handlers or services.

Application shell

Authentication partials

UI partials

Alpine components and stores

resources/assets/js/App.js registers the following names globally with Alpine. Use them as x-data="name" or x-data="name(...)" in BXM views. Form components make remote requests to the matching handler routes and expect the CSRF token supplied by their view, sent through fetchWithCsrf() (see CSRF on mutating requests).

Application shell and authentication

Admin and profile forms

UI components and global APIs

The source also contains Header.js, Sidebar.js, TopBarNotifications.js, and Logo.js. Their exports are available for local imports, but they are not currently registered by App.js; register them with Alpine.data() before using them as global x-data components.

Stores, utilities, and magic properties

AlpinePlugins.js installs Collapse, Focus, Mask, and Persist. passkeys.js provides the browser-side WebAuthn integration. Keep new reusable browser APIs documented here and add their registration/import to App.js when they are global.

CSRF on mutating requests

Every component action that sends a non-GET request goes through fetchWithCsrf() (utils/csrf.js) instead of calling fetch() directly. This is the one encapsulated place mutating requests are built, so the token-recovery behavior - and anything added to it later (request/response hooks, global headers, telemetry) - only has to change here rather than in every component that happens to mutate state.

Why it has to recover at all. A component's csrfToken is embedded once, when its view renders. The server can invalidate it while the page is still open, in two ways cbcsrf's own docs call out: csrfField() (the mixin behind every hidden csrf input) force-rotates the session's token on its first use per request, so any page that renders it - Settings, the passkey-required page, the auth pages - silently invalidates the token sitting in every other open tab; and a token expires a fixed time after it was created, not after the page loaded, so a page rendered late in a token's life can be served one with only seconds left. Either way, a component's embedded token can go stale before the user finishes typing.

The contract:

export async function fetchWithCsrf( component, url, method, buildRequest ) { /* ... */ }
export async function refreshCsrfToken( component ) { /* ... */ }

• component is the Alpine component instance (pass this). It must expose a mutable csrfToken property - fetchWithCsrf() reads it to build the request and, on a stale-token retry, overwrites it with the session's current token via refreshCsrfToken().
• buildRequest( csrfToken ) returns the method-specific RequestInit fields (headers, body, credentials, etc.) for the given token. It is called again on retry, so it must build the body fresh each time rather than closing over a value computed once - this is what lets the same helper cover URLSearchParams, JSON.stringify(), and FormData bodies alike.
• On a 403, fetchWithCsrf() calls refreshCsrfToken() and, if it obtained a genuinely new token, replays the request once with buildRequest() called again. A second 403 (e.g. a real authorization failure, or a session that has expired entirely) is returned as-is - callers still need their normal error handling for that case.

const response = await fetchWithCsrf( this, "/permissions", "POST", ( csrf ) => ( {
	headers : { "Content-Type": "application/x-www-form-urlencoded" },
	body    : new URLSearchParams( { permission: this.form.permission, csrf } ),
} ) );

const response = await fetchWithCsrf( this, form.action, "POST", ( csrf ) => {
	const formData = new FormData( form );
	formData.set( "csrf", csrf );
	return { body: formData, credentials: "same-origin", headers: { Accept: "application/json" } };
} );

Only GET/HEAD reads skip fetchWithCsrf() and call fetch() directly - they carry no CSRF token and cannot 403 for one. A handful of cbSecurity module endpoints (the WebAuthn passkey ceremony routes) are also called with plain fetch(): they authenticate through the WebAuthn ceremony itself, not this app's CSRF token, so they are out of scope for this helper. Every other mutation in resources/assets/js/components/ goes through fetchWithCsrf(); keep new form components consistent with that when they add a request that changes server state.

Avatars & branding logo

User avatars and the application branding logo are stored on the private cbfs assets disk (see Configuration) and streamed out by Assets.bx (see Handlers & Routing) rather than served as static files.

• Display goes through the _components/ui/avatar partial: it renders <img src="/avatars/:userId/:size"> when hasAvatar is true, and falls back to an initials <span> otherwise. It is wired into the sidebar, topbar, and Users listing table (server-projected hasAvatar field), and inline in the Users detail page (x-show/x-cloak toggling on user.hasAvatar, since that page's avatar sits inside an Alpine-driven summary card rather than a static partial).
• Upload/remove for the current user's own avatar lives on the Profile page, owned by profileForm (ProfileForm.js): a hidden file input reads the selected image as a base64 data URI (readFileAsDataUrl()) and posts it to POST /profile/avatar; DELETE /profile/avatar removes it. Both bump a version counter used as a cache-busting query param on the streamed URL, since the file path itself does not change between uploads.
• The branding logo gets the same upload/remove treatment on the Settings page, via the logoUploader component (LogoUploader.js) against POST/DELETE /settings/logo. It replaces the cbAppLogo setting's text input value with the streamed path (/branding/logo/lg) on upload, and restores the configured default on removal — the manual URL text input and live <img> preview keep working exactly as before for anyone who wants to point cbAppLogo at an external URL instead.
• Both upload endpoints accept the same shapes: images are decoded server-side with BaseSecureHandler.decodeDataUri(), then resized/cropped into sm/lg JPEG (avatar) or PNG (logo) variants by ImageService (app/models/system/ImageService.bx).