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.

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.